This post will show how to configure a generic .net application to use the WS-Federation protocol to authenticate to the NetIQ Access Manager Identity Server. The steps that need to be performed are:
Download and install Windows Identity Foundation SDK
Prepare the Identity Server metadata
Modify the application configuration using the Windows Identity Foundation Federation Utility
Apply required manual modifications to the application configuration
Configure the application as a WS-FED Service Provider on the Identity Server
(Optional) Add validation of the authorization claim to the application
You must know the URL where the application will be deployed. In this tutorial will use "http://localhost:2112". Note: This can be changed later but the Federation Utility automates all the configuration needed if you supply it with the correct URL.
Install the SDK on the workstation where you have the application source and Visual Studio2013.
Task 2. Preparing the Identity Server Metadata
The Windows Identity Foundation Federation Utility uses the Identity Server metadata to configure the application for WS-FED authentication. The utility expects the metadata in a very specific format. Currently, the NetIQ Access Manager WS-FED provider metadata does not provide the required format. An enhancement request has been made but until it has been implemented you will need to manually modify the metadata so that it will be accepted by the utility. NOTE: an example metadata document is available here: ModifiedMetadataExample
To make the modifications you will start with the current WS-FED and SAML2 metadata documents from the identity Server. The production metadata documents can be obtained from:
Save these two files to disk then open the SAML2 document in an editor that can deal with UNIX/Linux line endings.
The first thing we will need to change is the namespace declaration of the root EntityDescriptor element.
Search for and remove all instances of "md:" in the document
In the EntityDescriptor tag, modify the namespace declaration by deleting the characters ":md". The namespace attribute should be as shown below:
Since we are modifying the metadata we must now remove the existing digital signature.
Delete the "ds:SignedInfo" element and all the elements inside it
Delete the "SignatureValue" element and all the elements inside it
The next step is to add a "RoleDescriptor" element that contains the WS-FED metadata. NOTE: The federation utility cannot parse this element properly if it contains line breaks. In the appendix is an example RoleDescriptor element that can be used as a template.
Paste the template element below the opening tag of the EntityDescriptor element as shown:
Change the ServiceDisplayName attribute to "<the domain name of your IDP>" as shown
Change the domain name in the endPointReference elements to "<the domain name of your IDP>" as shown
Open the WS-FED metadata and copy the certificate data from within the "ds:x509certificate" element to the clipboard NOTE: Do not copy the tags.
Select the certificate data in the example RoleDescriptor element and then paste the copied certificate data in its place.
(Optional) Within the "fed:ClaimTypesOffered" element, edit the claims provided by the Identity Server to match the attributes that are to be sent during authentication. NOTE: you can add attributes without modifying this element. Making this change just allows the Federation Utility to pre-populate the claim references in the application configuration.
Save the modified metadata file for use in the next task.
Task 3. Modifying the Application Configuration Using the Windows Identity Foundation Federation Utility
Make a backup copy of the applications Visual Studio project
Browse to C:\Program Files(x86)\Windows Identity Foundation SDK/v4.0 and execute FedUtil.exe
Click the "Browse" button to the right of the "Application configuration location" field and then select the Web.config file inside your application project directory. See below:
In the Application URI field enter the URI that will be used to access the application. See above:
Click "Next". In the example a warning is displayed because the URL is hot using HTTPS. Click "Yes" to continue.
Click the radio button corresponding to "use an existing STS"
Click "Browse" and select the Identity Server metadata file modified earlier
Click on the "Test location" button. If the metadata is well formed it will be displayed in your default web browser. If this step fails, resolve metadata format issues and try again.
Click on the "Next" button. If the utility can successfully parse the metadata you will see the warning shown below, "The WS-Federation metatdata document is unsigned". If you get any other result, resolve metadata format issues and try again.
Click on the "Yes" button to continue using the unsigned metadata.
On the "Security token encryption" page select "No Encryption". No sensitive data is being passed so encryption is not required. If you choose to use encryption you will need to generate or select a certificate. That certificate will be needed later when configuring the Identity Server Service Provider for this application. See Below:
The utility will display the claims offered by the identity Server. Click "Next".
The utility will display the summary page. Click "Finish".
The utility will display the Success dialog. Click "OK" to close the utility. NOTE: Do not select the check box to schedule a task to periodically update the metadata.
Task 4. Apply Manual Modifications to the Application Configuration.
Open the application project in Visual Studio and select the Web.config file for editing.
The "httpModules" element is used for IIS version 6. You will need to comment out the entries that the Federation Utility added so that we can deploy the application on IIS version 7 as shown below:
Next you will need to add assemblies used by WIF to the assemblies element and add an httpRuntime element as shown below:
Open a file system explorer window and navigate to "C:\Program Files(x86)\Windows Identity Foundation SDK/v4.0/Samples/Quick Start/ClaimsAwareWebAppWithManagedSTS" as shown below:
Select "App_Code" and drag it into Visual Studio. Drop it on "IndlagtePatienter" in the Solution Explorer window. This will add the WIF example code needed to validate the assertion from the Identity Server to the application.
Before dragging in "App_Code"
After dragging in App_Code
Select the application in the Solution explorer window as shown above.
In the Properties window disable Anonymous Authentication and Windows Authentication as shown below:
Task 5. Configuring the Application as a WS-FED Service Provider on the Identity Server
Create a new attribute set for the Service Provider
Add mappings for the attribute "cn" as shown below:
Add a mapping for "All Roles" as shown below:
Add mappings for any other attributes that you would like to send to the application. NOTE: Only "cn" and "All Roles" are needed for this application. Your attribute set should look similar to the one shown below:
Edit your Identity Server configuration and navigate to Identity Servers ---> WS Federation.
Select "New" ---> "Service Provider" and the Service Provider Wizard will open as shown below. Enter the URL of the application into the "Provider ID" and "Sign-on URL" fields. NOTE: This URL must match the one you used on the first page of the Windows Identity Foundation Federation Utility!!
Even though we are not using encryption, the Access Manager Administration Console forces us to select a certificate. Choose any certificate in DER format. This certificate will not actually be used. NOTE: If you did enable encryption when you configured the application you MUST select that same certificate here.
Click "Next" and "Finish" to close the wizard.
Select the new Service Provider then select "Attributes".
In the Attribute set dropdown, select the attribute set you created earlier.
Select the "cn" and "All Roles" attributes to be sent with the authentication as shown below and click "Apply"
Select "Authentication Response"
Click the "Unspecified" radio button and select "Ldap Attribute:cn" as shown below:
Click "OK" to close the Service Provider.
Select "Policies" ---> "Master_Container".
Select "New" and then "Identity Server: Roles" in the Type dropdown. Enter a name for the policy.
In the "Condition Group 1" box select "New" --->"LDAP Group"
In the "Value" field, in the dropdown that shows "[Current]", select the user store ( must be the same one used for the authentication method) and then select the group that will be used to provide access to the application. It should look like the Condition below:
In the Action box, select "Activate Role" and enter the role name to be sent to the application.
Click "OK" twice
Click "Apply Changes"
Edit your Identity Server configuration and select "General" --> "Roles" as shown below:
Select the checkbox next to the new role then select "Enable".
Update the Identity Server.
Task 6. Add Validation of the Authorization Claim to the Application
At this point, any user that can successfully authenticate will be able to access the application. To restrict access to only members of the selected group, the application will need to validate that a "role" claim with the proper value was received from the Identity Server. The WIF sample application ClaimsAwareWebAppWithManagedSTS has examples of how to access the claims.