Integrating a .net application with Access Manager using WS-Federation

0 Likes
over 6 years ago
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:

  1. 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


Prerequisites



  1. 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.


  • You must have access to the application project


Task 1. Installing the WIF SDK



  1. Go to http://go.microsoft.com/fwlink/?linkid=179833 and download WindowsIdentityFoundation-SDK-4.0.msi

  • 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:

  • https://<your domain>/nidp/saml2/metadata

  • https://<your domain>/nidp/wsfed/metadata


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:


image002

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:


image003

  • 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


image008

  • 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



  1. 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:


image009

  1. 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.


image011

  1. Click the radio button corresponding to "use an existing STS"

  • Click "Browse" and select the Identity Server metadata file modified earlier


image013

  1. 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.


image015

  1. 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.


image017

  1. 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:


image019

  1. The utility will display the claims offered by the identity Server. Click "Next".


image021

  1. The utility will display the summary page. Click "Finish".


image023

  1. 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.


image025

Task 4. Apply Manual Modifications to the Application Configuration.



  1. 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:


image027

  1. Next you will need to add assemblies used by WIF to the assemblies element and add an httpRuntime element as shown below:


image029

  1. 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:


image031

  1. 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"

image033

After dragging in App_Code

image035

  1. Select the application in the Solution explorer window as shown above.

  • In the Properties window disable Anonymous Authentication and Windows Authentication as shown below:


image037

Task 5. Configuring the Application as a WS-FED Service Provider on the Identity Server



  1. Create a new attribute set for the Service Provider

  • Add mappings for the attribute "cn" as shown below:


image039

  1. Add a mapping for "All Roles" as shown below:


image041

  1. 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.


image043

  1. 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!!


image045

  1. 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"


image047

  1. Select "Authentication Response"

  • Click the "Unspecified" radio button and select "Ldap Attribute:cn" as shown below:


image049

  1. Click "Apply".

  • 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.


image051

  1. Click "OK".

  • 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:


image053

  1. 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:


image055

  1. Select the checkbox next to the new role then select "Enable".

  • Click "OK".

  • 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.

 

Labels:

How To-Best Practice
Comment List
Anonymous
Parents Comment Children
Related Discussions
Recommended