How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
How-to use Bluestem with ASP.NET
To get started quickly with Bluestem with ASP.NET V2 go directly to section 9 “Quick Startup Guide” Table of Contents How-to use Bluestem with ASP.NET ................................................................................. 1 1. What is ASP.NET for Bluestem ................................................................................. 2 2. Bluestem Basics .......................................................................................................... 2 3. ASP.NET Forms Authentication Basics ..................................................................... 4 4. Bluestem and ASP.NET Forms Authentication.......................................................... 5 5. Installing Bluestem for Windows IIS ......................................................................... 6 6. Downloading Library and Installing Samples ............................................................ 7 7. Creating Your Own ASP.NET Bluestem Application.............................................. 10 A. Versions 1.0 and 1.1 ........................................................................................... 11 i. Inside BlueStemLogin.aspx ............................................................................... 14 ii. Customizations: .............................................................................................. 14 iii. Web.config reference: .................................................................................... 17 B. Version 2.0 ......................................................................................................... 20 i. Inside Login.aspx ............................................................................................... 24 iii. Web.config reference for version 2.0: ............................................................ 31 iv. Displaying a Custom Access Denied Page: .................................................... 33 8. Authorization Tips .................................................................................................... 34 9. Quick Startup Guide ................................................................................................. 36 10. public static BluestemAuthentication members..................................................... 40
ASP.NET.Bluestem.HowTo.doc
Page 1 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
1. What is ASP.NET for Bluestem
ASP.NET for Bluestem is a .NET library and set of template files that allows you to use Bluestem Authentication in your ASP.NET applications without the hassle of dealing with Bluestem on each Web Form page. The .NET library and template use ASP.NET “Forms Authentication” in conjunction with a normal Bluestem application server installation to “convert” a Bluestem authentication credential to an ASP.NET Forms Authentication credential. From that point on your application needs to know nothing about Bluestem and it can use the Authorization section of the Web.config file to control access.
2. Bluestem Basics
Bluestem is fully described at https://www-s4.uiuc.edu/bluestem-notes/ In short, Bluestem is a software system which enables one or more high-security SSL HTTP servers in a single domain to provide reliable client identification for applications running on other authorized SSL HTTP servers within the domain. Bluestem provides client identification only. Decisions about whether an identified client is authorized to access a given application or resource are the responsibility of the applications. The basic protocol is described below:
1 - Client makes first reference to a Bluestem application server CGI. API senses
(by the absence of a Bluestem cookie) that the client requires identification, sets the cookie, and redirects the client to the login processing URL on a domain ID server.
2 – Bluestem Login CGI solicits the user's ID and informs the user of the server
and application requesting it.
3 – Bluestem Login CGI solicits the user's password, authenticates the ID/password, transmits the user's Bluestem ID to the application server which records it in its cache of identified clients, and redirects the client back to the application server CGI. 4 - On return to the application server, the API senses Bluestem cookie set in step
1, and consults its cache of identified clients. This diagram illustrates:
ASP.NET.Bluestem.HowTo.doc
Page 2 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
ASP.NET.Bluestem.HowTo.doc
Page 3 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
3. ASP.NET Forms Authentication Basics
When an ASP.NET application is configured for Forms Authentication and an unauthenticated user requests a page that requires authentication (and authorization) the following events occur: 1. Browser requests a page in an ASP.NET application that uses forms authentication. The ASP.NET framework checks to see if the user has already authenticated. If so, the Form contents are sent to the browser. 2. If the user is not already Authenticated the ASP.NET framework redirects the browser to the Authentication Form specified in the web.config file. This Form implements whatever is needed to authenticate the user and gives the users Identity to the Framework. 3. Browser is redirected back to the Form originally requested. Illustration:
Forms Authentication Overview
1, (3)
ASP.NET Forms
Browser ASP.NET Framework
2
Credentials
ASP.NET Authentication Form
ASP.NET.Bluestem.HowTo.doc
Page 4 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
4. Bluestem and ASP.NET Forms Authentication
When Bluestem and ASP.NET Forms Authentication are used together with the ASP.NET Bluestem library and templates the situation looks like this:
Putting It Together
1, (6)
ASP.NET Forms Credentials
Browser dotNET Land
2, 5
ASP.NET Framework Bluestem Class
Bluestem Land
3) NetID 4) Password
ASP.NET Authentication Form
Bluestem ID Server
Cache
Cache
1. The browser requests a page in an ASP.NET application that uses Forms authentication. The ASP.NET framework checks to see if the user has already authenticated. If so, the Form contents are sent to the browser. 2. If the user is not already authenticated the ASP.NET framework redirects the browser to the Authentication Form specified in the web.config file. This Form uses the .NET Bluestem Class to do some book keeping and redirects the browser to a Bluestem ID Server. 3. The user enters her NetID. 4. The user enters her password and is redirected back to the URL originally requested. 5. The Bluestem Class is again used to set the users Identity and redirects the user back to the originally requested Form. 6. The requested form is sent to the browser. Subsequent requests for any ASP.NET form in the application are sent back to the browser (after the framework has determined whether the user has already
ASP.NET.Bluestem.HowTo.doc Page 5 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
authenticated) without any redirection inclusion of bluestem code. All Bluestem related code is isolated to the one Form designated Applications Authentication Form.
5. Installing Bluestem for Windows IIS
In order the use ASP.NET with Bluestem you must first install the Bluestem Application Server. Instructions are found here: https://www-s4.uiuc.edu/bluestem-notes/appl-install-nt.html There are a few things to highlight since failing to do them can lead to much confusion. A. In the instructions at section 3 it is vital that step 14 be done. The dialog should look like this when completed:
The “Check that file exists” box MUST be unchecked. B. It is recommended that the ASP.NET user and the anonymous internet user account be given modify access to the entire “BluestemLib” directory tree.
ASP.NET.Bluestem.HowTo.doc
Page 6 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
C. If you are using IIS 6.0 or greater (Windows Server 2003 or Windows XP 64 bit edition) you must make certain that “Perl CGI Extension”, the version of ASP.NET you are using, and Active Server Pages are “Allowed” as shown below:
The above is described in section 7 of https://www-s4.uiuc.edu/bluestem-notes/appl-install-nt.html
6. Downloading Library and Installing Samples
Versions of the ASP.NET Bluestem library are available for three versions of .NET: • • • V1.0 V1.1 V2.0
https://netfiles.uiuc.edu/sinder/www/BlueStem.NET/ Download and unzip the version appropriate for your needs to a convenient location on your machine. Then depending on whether you prefer to use VB or C# select the appropriate sample directory:
ASP.NET.Bluestem.HowTo.doc
Page 7 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Version VB C# 1.0 Bluestem1VB Bluestem1CS 1.1 BluestemVB BluestemCS 2.0 BluestemV2VBExample BluestemV2CSExample Use the IIS Management Console to create a Virtual Directory pointed to the appropriate sample from the table above. Open the “Properties” Dialog for the new virtual directory. Select the ASP.NET tab (if it exists) and make sure this application is configured to use the appropriate version of ASP.NET. Example:
Select the “Directory Security” tab and in the “Secure communications” area click on Edit… Select “Require secure channel (SSL)”. On the “Virtual Directory” tab under Application Settings click the “Create” button if an application name is not filled in. On the Documents tab, Enable Default Document if it is not already enabled.
ASP.NET.Bluestem.HowTo.doc Page 8 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Open the Web.config file in a text editor. Modify this section to suit your installation of Bluestem:
Now use your web browser to test the application: https://yourmachine.xxx.xxx.xxx/Name_of_your_Virtual_Directory Note: Version 2 of the Bluestem ASP.NET Web.config file
section has some additional key/value pairs. Ignore those for now. They will be discussed later.
ASP.NET.Bluestem.HowTo.doc
Page 9 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
7. Creating Your Own ASP.NET Bluestem Application
ASP.NET for Bluestem 1.x and 2.0 use different programming models. 1.x versions attempt to provide the entire authentication facility through a single function call:
myBlueStem.Authenticate(Int32.Parse(Application["BluestemPrior"].ToString())); myBlueStem.Authenticate(ca, Int32.Parse(Application["BluestemPrior"].ToString()));
Customizations are handled with an optional callback function. The Authenticate method is intended to do the login and redirection. In version 2.0 the Authenticate method returns a Boolean indicating whether or not the user was authenticated. The developer can then do any customization desired and then invoke an ASP.NET bluestem method to log the user in. Sections A and B below describe versions 1.x and 2.0 separately.
ASP.NET.Bluestem.HowTo.doc
Page 10 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
A. Versions 1.0 and 1.1
To create your own ASP.NET Bluestem application, use Visual Studio (2002 or 2003) as appropriate to create your new application at an HTTPS location:
For a C# application open the code view for Global.asax.cs. In the Application_Start method, add the following code (you can copy from the example):
protected void Application_Start(Object sender, EventArgs e) { //---Virtual directory for Bluestem CGI scripts--------------------Application["BluestemVirtDir"] = ConfigurationSettings.AppSettings["BluestemVirtDir"].ToString(); //---Bluestem library files root directory (cache, etc)------------Application["BluestemLib"] = ConfigurationSettings.AppSettings["BluestemLib"].ToString(); Application["BluestemLog"] = ConfigurationSettings.AppSettings["BluestemLog"].ToString(); Application["CookieDelimPort"] = ConfigurationSettings.AppSettings["CookieDelimPort"].ToString(); Application["BluestemPrior"] = "-1"; if ( ConfigurationSettings.AppSettings["BluestemPrior"] != null) Application["BluestemPrior"] = ConfigurationSettings.AppSettings["BluestemPrior"].ToString(); }
ASP.NET.Bluestem.HowTo.doc
Page 11 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
For a VB application open the code view for Global.asax.vb. In the Application_Start method, add the following code (you can copy from the example):
Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs) ' Fires when the application is started '---Virtual directory for Bluestem CGI scripts--------------------Application("BluestemVirtDir") = _ ConfigurationSettings.AppSettings("BluestemVirtDir").ToString() '---Bluestem library files root directory (cache, etc)------------Application("BluestemLib") = _ ConfigurationSettings.AppSettings("BluestemLib").ToString() Application("BluestemLog") = _ ConfigurationSettings.AppSettings("BluestemLog").ToString() Application("CookieDelimPort") = ConfigurationSettings.AppSettings("CookieDelimPort").ToString() Application("BluestemPrior") = "-1" if ( ConfigurationSettings.AppSettings("BluestemPrior") != null) Application("BluestemPrior") = ConfigurationSettings.AppSettings("BluestemPrior").ToString() End Sub
Now open the Web.config file. Between the and the add
Modify the values as appropriate for your Bluestem installation. Replace the existing authentication section with:
Set up an authorization section according to your needs. Here are a few examples:
Allows only netid “sinder” (we use the full Bluestem/Kerberos name).
ASP.NET.Bluestem.HowTo.doc Page 12 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Allows any authenticated user.
Allows four specific NetIDs. Just before the add
get_aspx_ver.aspx is an invisible file added in ASP.NET 1.1. Without this section opening the project with Visual Studio can be problematic. Add a reference to Edu.Uiuc.Ccso.Bluestem.dll for V1.0 or Edu.Uiuc.Cites.Bluestem.dll for V1.1. Copy the following files into your application from the sample (you can drag and drop): BlueStemLogin.aspx BlueStemLogin.aspx.res BlueStemLogin.aspx.vb or BlueStemLogin.aspx.cs You can customize these files if you like. Now create some Web Form pages to test your application. Be sure to make one the starting page. You should be required to authenticate with Bluestem before you are permitted access to your pages. To find the identity of the Bluestem authenticated user: In VB: Me.Context.User.Identity.Name In C#: this.Context.User.Identity.Name To log the user out of ASP.NET:
ASP.NET.Bluestem.HowTo.doc Page 13 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
In VB: FormsAuthentication.SignOut() In C#: FormsAuthentication.SignOut(); Then send the user to the Bluestem logout: In VB:
Dim logout As String = Application("BluestemVirtDir") + "/logout.pl" Response.Redirect(logout)
In C#:
string logout = Application["BluestemVirtDir"] + "/logout.pl"; Response.Redirect(logout);
i.
Inside BlueStemLogin.aspx
The following is the same in VB or C#:
BlueStemLogin
The red section is used to display error messages, while the blue section includes a control to display a link to the page the user wants and script to automatically redirect the user there. These values are set at runtime. The C# and VB code is mostly cookie cutter stuff that can be copied and used without modification, but there are some opportunities for customization.
ii.
Customizations:
Page 14 of 40 Last Edited by Dale Sinder 9/24/2008
ASP.NET.Bluestem.HowTo.doc
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Versions 1.0 and 1.1 provide for customization via callback functions. Examples from the sample code are shown below. If you provide a callback to the Authenticate Method your custom method will be called after the user is Bluestem authenticated but before they are redirected to the target page. You have the opportunity to do things such as set session variables, do database authorization lookups, etc. Finally, you have final say over whether or not the user is redirected to the target page. The custom callback returns true to indicate that the user should be allowed to proceed or false to indicate that user should not be allowed access. VB code:
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load 'Put user code to initialize the page here Response.Cache.SetCacheability(HttpCacheability.NoCache) 'Turn off caching If Convert.ToBoolean(Application("AppOff")) Then 'Allow app to be turned off errorLabel.Text = "The Web application is not available at this time." errorLabel.Visible = True linkLabel.Visible = False Return End If myBlueStem = New Edu.Uiuc.Ccso.Bluestem.BlueStem() Dim href As String ' Optional CustomAuthenticate (Option 1) Dim ca As Edu.Uiuc.Ccso.Bluestem.CustomAuthenticate ca = New Edu.Uiuc.Ccso.Bluestem.CustomAuthenticate(AddressOf MyCallBack) href = myBlueStem.Authenticate(ca, Int32.Parse(Application("BluestemPrior").ToString())) ' Option 2 – no CustomAuthenticate href = myBlueStem.Authenticate() ' href = myBlueStem.Authenticate(Int32.Parse(Application("BluestemPrior").ToString())) ' end of options If (href <> Nothing) Then ' handle intermediate panel setup here linkLabel.Text = "Click here to enter" & _ "" linkLabel.Visible = True errorLabel.Visible = False End If End Sub ' Used with Option 1 – Do your custom actions here. Public Function MyCallBack() As Boolean Dim idfull, Username, domain, authmethod As String idfull = Me.myBlueStem.FullID Username = Me.myBlueStem.UserName domain = Me.myBlueStem.Domain authmethod = Me.myBlueStem.AuthMethod Session("UserName") = Username Session("RealNetid") = Username If (Not domain.Equals("uiuc.edu")) Then errorLabel.Text = "You are not permitted access
You must login in the uiuc.edu domain." ASP.NET.Bluestem.HowTo.doc Page 15 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
errorLabel.Visible = True linkLabel.Visible = False Return False End If If (Not authmethod.Equals("kerberos")) Then errorLabel.Text = "You are not permitted access
You must login in using the kerberos authetication method." errorLabel.Visible = True linkLabel.Visible = False Return False End If Return True End Function
C# Code:
private void Page_Load(object sender, System.EventArgs e) { // turn off caching Response.Cache.SetCacheability(HttpCacheability.NoCache); // provide ability to turn app off if (Convert.ToBoolean(Application["AppOff"])) { errorLabel.Text = "The Web application is not available at this time."; errorLabel.Visible = true; linkLabel.Visible = false; return; } string href; myBlueStem = new BlueStem(); // Option 1 – with custom actions CustomAuthenticate ca = new CustomAuthenticate(this.MyCallBack); href = myBlueStem.Authenticate(ca, Int32.Parse(Application["BluestemPrior"].ToString())); //Option 2 – no custom actions href = myBlueStem.Authenticate( Int32.Parse(Application["BluestemPrior"].ToString())); // End options if (href != null) { // handle intermediate panel setup here linkLabel.Text = "Click here to enter" + ""; linkLabel.Visible = true; errorLabel.Visible = false; } }
// Used with Option 1 – Do your custom actions here. /// /// Do post bluestem authenticate and set Session Vars /// /// True if user passes post bluestem authentication public bool MyCallBack() { string idfull, Username, domain, authmethod; idfull = this.myBlueStem.FullID; ASP.NET.Bluestem.HowTo.doc Page 16 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Username = this.myBlueStem.UserName; domain = this.myBlueStem.Domain; authmethod = this.myBlueStem.AuthMethod; Session["UserName"] = Username; Session["RealNetid"] = Username; if ( ! domain.Equals("uiuc.edu")) { errorLabel.Text = "You are not permitted access
You must login in the uiuc.edu domain."; errorLabel.Visible = true; linkLabel.Visible = false; return false; } if ( ! authmethod.Equals("kerberos")) { errorLabel.Text = "You are not permitted access
You must login in using the kerberos authetication method."; errorLabel.Visible = true; linkLabel.Visible = false; return false; } // Add other checks as needed. Perhaps to a database // lookup to see if user qualifies. Or look up Group // membership in AD to see if user is permitted... /* HttpContext ctx = HttpContext.Current; PersonStatus ps = new PersonStatus(ref ctx); bool hasChanged = ps.HasChanged; bool canChange = ps.CanChange; bool canSet = ps.CanSet; string banner_login = ps.BannerLogin; Session["HasChanged"] = hasChanged; Session["CanChange"] = canChange; Session["CanSet"] = canSet; Session["BannerLogin"] = banner_login; */ return true; }
iii.
Web.config reference:
The following keys should be in the section, which immediately follows the line:
1. 2. 3. 4. 5. 6. key="BluestemLib" value="C:\Bluestem\lib" /> key="BluestemLog" value="C:\Bluestem\Logs\bluestem.net.log" /> key="CookieDelimPort" value="_"/> key="BluestemPrior" value="-1" /> key="AppOff" value="false" />
Line 1 refers to the Bluestem virtual directory on your web server. Line 2 refers to the disk location of your Bluestem Lib directory. Line 3 refers to the disk location of the Bluestem.NET log file.
ASP.NET.Bluestem.HowTo.doc Page 17 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Line 4 defines the bluestem cookie port delimiter Line 5 defines the prior authentication parameter (-1 for no prior authentication, up to 7200 for use of prior authentication up to 2 hours) Line 6 is used to disallow new people from logging into the application be setting the value to true.
ASP.NET.Bluestem.HowTo.doc
Page 18 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
The authentication section should look like this:
The authorization section specifies which users may use the application:
ASP.NET.Bluestem.HowTo.doc
Page 32 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
iv.
Displaying a Custom Access Denied Page:
If you intend to have a page that displays a custom message regarding a user being denied access configure a location section: In the Global.asax implement the Application_EndRequest method: C#:
void Application_EndRequest(Object sender, EventArgs e) { if (this.Response.StatusCode == 302 && this.Request.IsAuthenticated && (this.Request.Url != this.Request.UrlReferrer)) this.Response.Redirect("~/NoAccess.aspx"); }
VB:
Sub Application_EndRequest(ByVal sender As Object, ByVal e As EventArgs) If (Me.Response.StatusCode = 302 And _ Me.Request.IsAuthenticated And _ (Me.Request.Url <> Me.Request.UrlReferrer)) Then Me.Response.Redirect("~/NoAccess.aspx") End If End Sub
Known Issue: In some cases the above code may incorrectly display the NoAccess Page. If this occurs, comment out the contents of Application_EndRequest.
ASP.NET.Bluestem.HowTo.doc
Page 33 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
8. Authorization Tips
• BluestemAuthentication saves a reference to the object used to authenticate and log the user in to a Session variable. You may retrieve the following static properties: o BluestemAuthentication.IsAuthenticated o BluestemAuthentication.BluestemFullUserId o BluestemAuthentication.BluestemShortUserId o BluestemAuthentication.BluestemDomain o BluestemAuthentication.BluestemAuthMethod If you use the LoginStatus Web Server control implement the OnLoggingOut and OnLoggedOut Event Handlers:
•
C#:
protected void LoginStatus1_LoggingOut(object sender, LoginCancelEventArgs e) { BluestemAuthentication.BluestemLogout(); } protected void LoginStatus1_LoggedOut(object sender, EventArgs e) { BluestemAuthentication.BluestemLogoutRedirect(); } VB: Protected Sub LoginStatus1_LoggingOut(ByVal sender As Object, ByVal e As System.Web.UI.WebControls.LoginCancelEventArgs) Handles LoginStatus1.LoggingOut BluestemV2Lib.BluestemAuthentication.BluestemLogout() End Sub Protected Sub LoginStatus1_LoggedOut(ByVal sender As Object, ByVal e As System.EventArgs) Handles LoginStatus1.LoggedOut BluestemV2Lib.BluestemAuthentication.BluestemLogoutRedirect() End Sub
ASP.NET.Bluestem.HowTo.doc
Page 34 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
• C#:
You may do runtime group membership tests using the RolePrincipal class
RolePrincipal rp = new RolePrincipal(this.Context.User.Identity); string[] groups = rp.GetRoles(); // get string array of groups // check membership for a group bool iscampusAccount = rp.IsInRole("uiuc campus accounts");
VB:
Dim rp As RolePrincipal = _ New RolePrincipal(Me.Context.User.Identity) Dim groups As String() = rp.GetRoles()' get string array of groups ' check membership for a group Dim iscampusAccount As Boolean = rp.IsInRole("uiuc campus accounts")
ASP.NET.Bluestem.HowTo.doc
Page 35 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
9. Quick Startup Guide
This guide is intended to quickly get you started using Bluestem ASP.NET V2 with a role provider by starting with a simple application that demonstrates the basics. There are both VB and C# samples. These examples demonstrate the simplest login technique. The samples provide the following starting elements: • • • • • A starting Web.Config A Bluestem ASP.NET login page A sample page to display a “No access” message if a user is denied access after successful authentication A starting Global.asax that routes the user to the “NoAccess” page when appropriate. A Default page that displays the users Identity, the Active Directory Groups the user is a member of, a way to check for membership in a specific Active Directory Group at run time.
The prerequisites include: • • • • • Visual Studio 2008 Windows Server 2003 or greater, Windows Vista or greater with IIS An IIS Certificate A working Bluestem installation – See section 5 An Active Directory Service Account that is registered as a service account – see page 28.
Setup steps: 1. 2. 3. 4. 5. 6. 7. Download and unzip the distribution to a location of your choice. Use Visual Studio 2008 to create a new Blank Solution Add BluestemV2Lib to the solution Use the IIS manager to add either BluestemV2VBStarter or BluestemV2CSStarter as a new virtual directory. If needed convert the virtual directory to an application. Require SSL on the application Enable the following Authentication methods in IIS: Anonymous, Forms, Windows. Ignore any warnings about simultaneous use of redirect-based and challenge-based authentication Configure the application to use an Application Pool that uses an Active Directory Account that is registered as a service account as its Identity. Using the Visual Studio 2008 File Menu, Add - Existing Web Site. Choose Local IIS and your new application. Save the solution and exit Visual Studio.
Page 36 of 40 Last Edited by Dale Sinder 9/24/2008
8. 9.
ASP.NET.Bluestem.HowTo.doc
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
10. Make a backup copy of the solution file. 11. Using a text editor open the solution file. You should find a line that looks like this: Project("{E24C65DC-7377-472B-9ABA-BC803B73C61A}") = " yourapplicationname ", "https://localhost/yourapplicationname", "{E681D69B-4DB4-4055-98A1B90817E1A167}" 12. Replace the “localhost” part with the fully qualified domain name of your host machine that matches your SSL certificate. The resulting line might look like this: Project("{E24C65DC-7377-472B-9ABA-BC803B73C61A}") = " yourapplicationname ", "https://myhost.ad.uiuc.edu/yourapplicationname", "{E681D69B-4DB4-4055-98A1B90817E1A167}" 13. Do not change anything else. Save the file. 14. Reopen the solution with Visual Studio 2008. 15. Modify the appSettings keys BluestemLib, BluestemLog, BluestemVirtDir as appropriate for your bluestem installation. You should now be able to edit and run/debug the web application in Visual Studio 2008. Notice that the authorization section allows any domain user to view pages:
Try changing the allow to use a group you are not a member of. For example:
Try adding other groups:
You can also use user names:
ASP.NET.Bluestem.HowTo.doc Page 37 of 40 Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Things to take note of in Web.config: • • • • • The appSettings keys BluestemLib, BluestemLog, BluestemVirtDir must be adjusted as appropriate for your bluestem installation. If this is not done the application will not work and will fail in confusing ways. The appSettings key BluestmPrior may be adjusted as high as 3600 if/when Bluestem “Prior Authentication” is released. The appSettings key CookeDelimPort should not be changed. The appSettings key AD-DC.LDAP.ROOTS identifies the campus primary and secondary Active Directory domain controllers. This should not be changed. The appSettings key BLUESTEM_QUALIFIERS_AUTO or BLUESTEM_QUALIFIERS are the suffixes for proper Bluestem authentication at UIUC. If a user is Bluestem authenticated by Kerberos or if the Kerberos principal exists but the user is authenticated by Active Directory the Bluestem suffix will be “@uiuc.edu/kerberos”. If the Kerberos principal does not exist and the user is authenticated by Active Directory the Bluestem suffix will be “@uiuc.edu/ad”. This would usually be the case for application servers that have bluestem Active Directory authentication enabled and the login ID is not in the “Campus Accounts” OU. If BLUESTEM_QUALIFIERS_AUTO is configured the Authenticate method will automatically call the Require method. In order for the RoleProvider to work either BLUESTEM_QUALIFIERS_AUTO or BLUESTEM_QUALIFIERS must be configured. The appSettings key AUTOLOGIN is used to flag if the Authenticate method should automatically call the AspFormsLogin method. Both AUTOLOGIN and BLUESTEM_QUALIFIERS_AUTO must be configured to cause the Authenticate method to automatically call the AspFormsLogin method. The sessionState timeout and the roleManager cookieTimeout should be greater than the forms timeout. If authorization roles are to be used the roleManager section must be configured to use the BluestemV2Lib.BluestemADRoleProvider. If you wish to display a page when a user is properly authenticated but not authorized to view a page you must configure a location section as shown in the example Web.Config so that all users will be permited to see the page. The Gobal.asax must also implement a Application_EndRequest event handler to route the user to the “NoAccess” page as shown in the example Gobal.asax. The authentication section must be set to use “Forms” mode.
•
• • •
•
ASP.NET.Bluestem.HowTo.doc
Page 38 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
Things to note in the code: • • All methods and properties of the BluestemAuthentication class are static. You may not create an instance of the class. There are three things that must be done in the code for the login page assuming AUTOLOGIN and BLUESTEM_QUALIFIERS_AUTO are configured: o Call BluestemAuthentication.Authenticate()and return if not true. o Add some javascript to provide browser based redirection to the url target page. The Literal “litScript” is used for this purpose. You can use the
BluestemAuthentication.DefaultRedirectClientJavascript
•
•
property to get this value. o Provide a link for the user to click on if the redirection should fail. The hyperlink “gotoLink” is used for this purpose. You can use the BluestemAuthentication.DefaultUrl property to get this value. The code for the Default page demonstrates the use of a couple of BluestemAuthentication class members: o BluestemAuthentication.BluestemFullUserId gets the full Bluestem ID of the user. o BluestemAuthentication.BluestemLogout() logs the user out. The Default page also shows how to use the RoleProvider at runtime. A new RolePrincipal must first be created:
RolePrincipal rp = new RolePrincipal(this.Context.User.Identity);
one can then check for membership in a specific AD group:
bool result = rp.IsInRole("a group common name");
one may also get a complete list of group memberships:
string[] = rp.GetRoles();
It is generally not necessary or desireable to get the complete list of roles at runtime. If you have a set of pages that should be granted different access that the rest of the application you can put them in a sub-folder and control access by providing a Web.Config in that folder that overrides the authorization section. However, there may be special cases where it is desireable to get the complete list at runtime.
ASP.NET.Bluestem.HowTo.doc
Page 39 of 40
Last Edited by Dale Sinder 9/24/2008
How-to use Bluestem with ASP.NET
The University of Illinois at Urbana-Champaign
Integration and Software Engineering
10.
• • • • • • • • • • • • • • • • • • •
public static BluestemAuthentication members
bool Authenticate() - Perform Bluestem Authentication bool Authenticate(int) - Perform Bluestem Authentication with PriorAuth bool Authenticate(Literal, HyperLink) - Perform Bluestem Authentication and set java script and hyperlink redirects if successful bool Authenticate(int, Literal, HyperLink) - Perform Bluestem Authentication with PriorAuth and set java script and hyperlink redirects if successful bool Require(string, string) - Require domain and authmethod bool Require(string) - Require suffixes separated by ; string AspFormsLogin() - Normal Forms login string AspFormsLogin(string)- Forms login to a different URL void ASPFormsLogout() - Forms logout void BlusetemLogout() - Forms and Bluestem logout – deletes Bluestem cookie void BlusetemLogoutRedirect() – Assure that redirect to Bluestem logout page is done string MakeRedirectClientJavascript(string) - a client java script segment to redirect to the provided url bool IsAuthenticated - true if the user has been authenticated string BluestemFullUserId - Example: sinder@uiuc.edu\kerberos string BluestemShortUserId - Example: sinder string BluestemDomain - Example: uiuc.edu string BluestmAuthMethod - Example: Kerberos string DefaultUrl - URL to which user should be redirected after login string DefaultRedirectClientJavascript – a client java script segment to redirect to the login page
ASP.NET.Bluestem.HowTo.doc
Page 40 of 40
Last Edited by Dale Sinder 9/24/2008