Install and Configure a Simple .Net 4.5 Sample Federated Application (aka.ms/SampApp)

  • Article

I do this from time to time and often have to figure out what I didn't do right :(  So this time, I thought I would document the process so you can use these steps and enjoy the sample application too, without any pain and suffering; which has already been done for you.  Special thanks to my MCS dev buddies who have assisted and corrected me every time I need help (Doug Seelinger and Paul Wu)

This assumes you have at least 1 Windows 2012 R2 Domain Controller, 2012 R2 AD FS Server and another application server to use in a lab or production environment.  It is assumed that all networking is in place and the AD FS role is installed and functional. Also, if you use an existing IIS Web Server or create a new one, as done below with PowerShell, it is assumed that you will add an SSL cert and enable the SSL bindings.  You can use a wildcard cert or else issue a certificate just for that application server.  If you have never done this before see How to Setup SSL on IIS 7 (Still applies).  Need a lab environment?  See Set up the lab environment for AD FS in Windows Server 2012 R2. NOTE:   that does also have a sample claimsapp to use, but it is older and based on .Net 3.5.  Since Windows Server 2012 R2 by default has .Net 4.5 included, the sample claims aware application we have below looks a little nicer and requires fewer pre-requisites.

The sample application is zipped below at the bottom of this blog for you to modify and use. Also, 2 Claim rules are included: just extract the two individual rules to the C:\drive on your AD FS server. With all the basics in place, you can use this sample application to show claims for any user by logging onto this application.  If you want to test various claim rules and their effect on the SAML token, you can try your claim rules out on the Sample Application Relying Party that you will create below for the zipped up sample application you will install.  To learn more about the various Claim Rule options see Configuring Claim Rules. If you then want to try these rules out on a new Relying Party trust for other federated applications, see Create a Relying Party Trust.

INSTALL IIS Web Server for Your Test Application

  • Install IIS on a separate application server from the AD FS server.  In my lab in contoso.com, I called this server APP1. Feel free to use a different application server name, but if you do, you will just need to update that hostname wherever mentioned below.
    • Open Powershell_ISE as an administrator and run the following command

Install-WindowsFeature Web-Server, Web-App-Dev, Web-Net-Ext45, Web-Asp-Net45, Web-Mgmt-Tools,Web-Mgmt-Console,NET-Framework-45-Features,NET-Framework-45-Core,NET-Framework-45-ASPNET

  • Create a Service Account just for the IIS Default AppPool e.g. contoso\Svc_AppPoolAcct. Update the values in red for your environment if different.
    • Run the following 2 command on your Domain Controller (AD FS can be collocated here as well) with an elevated PowerShell_ISE.

New-ADUser -Name Svc_AppPool -AccountPassword (ConvertTo-SecureString -AsPlainText "P@ssw0rd" -Force) -Company Contoso -Description "App Pool Account" -DisplayName Svc_AppPool -Enabled $true -PasswordNeverExpires $true -SamAccountName Svc_AppPool -UserPrincipalName Svc_AppPool@contoso.com

Add-ADPrincipalGroupMembership -Identity Svc_AppPool -MemberOf IIS_IUSRS

NOTE

  1. When I did this, I already had my certificate bound in IIS to 443.  please make sure you do that too!

MODIFY SampApp for Your Environment

Copy the entire SampApp Folder (Extracted) to C:\Inetpub\wwwroot\ on the application server. There are two levels of zipped files below.  The main download below contains one zip file for the SampApp and then another for the SampAppRules.

  • Go to the AD FS server and open PowerShell_ISE  from the Start menu
  • Type Get-AdfsCertificate -CertificateType Token-Signing | Select -ExpandProperty Thumbprint and copy the entire Thumbprint value at the very end (you will need this value for the next step)
  • Open the SampApp folder that you extracted in the wwwroot folder above and Edit the Web.config  by right clicking on the file and selecting Edit
  • Type Ctrl + F  and search for the word thumbprint. There will be 3 instances.  Replace the value within the parenthesis just after "thumbprint, for each of those, with the value copied above.
  • Search for Contoso and replace with your domain name if different.  This assumes that BOTH AD FS and your application are in the same domain.  There will be 11 instances. If your IIS server is in another domain, use that domain name in the 2 instances where you see app1 as a host name.
  • Likewise, change app1 to be the hostname of your web server in those two instances if it is different. Close the file.
  • From the original Windows Explorer window, in the SampApp folder, double click on the FederationMetadata folder, 2007-06, and right click to EDIT FederationMetadata.
  • Do a Ctrl + H and TYPE app1.contoso in the Find what: field. Type in the <host.domain> name for your lab or environment (if different) in the same format and click Replace All.  This should update 4 instances.  Save and close this.

ADD SampApp to IIS

  • Goto the Start screen and type intemgr. Then press ENTER to open  Internet Information Services Manager
  • Select Application Pools in the left side of the console
  • In the center, select DefaultAppPool , right click on it and select Advanced Settings
  • In the Advanced Settings dialog box, select Identity on the left.  Then, click on the ellipses ( …) to the right of the service account listed
  • In the Application Pool Identity dialog box, select the Custom Account radio button and then click Set…
  • Enter the AppPool service account created above, in the format of <Domain>\<UserName> in the User Name field. Enter the password in both fields and click OK twice.
  • Look 3 rows further down for Load User Profile. Select the drop-down box to the right and SELECT True and then click OK
  • On the left side of IIS Manager, expand Default Web Site and select SampApp. Right click on SampApp and select Convert to Application.  Click OK
  • Select Default Website on the left and then click Restart on the right in the Actions pane.

ADD Sample Application as a Relying Party in AD FS

  • Return to the AD FS Server and open the  PowerShell_ISE. NOTE: make sure the Rules are extracted from their zipped folder and unzipped (2 files) to C:\
    • Run the following command. NOTE: update <app1.contoso> to reflect your host.domain name in the URL string below after -MetadataURL.

Add-AdfsRelyingPartyTrust -Name "Sample Claims Aware Application" -IssuanceAuthorizationRulesFile C:\IssuanceAuthorizationRules.txt -IssuanceTransformRulesFile C:\IssuanceTransformRules.txt -MetadataUrl https://app1.contoso.com/sampapp/federationmetadata/2007-06/federationmetadata.xml

  • Open Internet Explorer from the AD FS Server and access https://app1.contoso.com/SampApp/, with your specific URL for your environment :)
  • If you get prompted for credentials, it is because you need to add the AD FS URL to the Trusted Intranet zone in Internet Explorer (See How) and then you will no longer get prompted!  Success will look like this...

I really hope this helps to give you a simple Sample Claims Aware Application  to deploy so you can then test various claims rules for your federation scenarios.

Until the next Tangent Thought....

Mark from Microsoft Consulting Services

SampApp and Rules.zip

Comments

  • Anonymous
    September 05, 2016
    Hi there,Three things that would help the readers configure and have the sample application refered in this article running sucessfully:- Section "MODIFY SampApp for Your Environment" is missing the update of "sts.contoso.com..." in Web.config, you should replace these with you AD FS hostname, i.e. "adfs1.contoso.com..."- Make sure the "authority name" and "add name" within the "authority" element in Web.config matches exactly the hostname of the AD FS server, these are case sensitive regardless of what other documentation says- A reminder that running the sample application without a slash "/" at the end of the URL (i.e. https://app1.contoso.com/SampApp instead of https://app1.contoso.com/SampApp/") will trigger a redirect exception.
  • Anonymous
    March 22, 2017
    Thanks for sharing
  • Anonymous
    March 10, 2018
    Thanks ever so much for posting :) this is exactly what I have been looking for to help me learn more about AD FS and in particular how to write claims rules etc. :)Thanks againJo