WCF Federated Authentication Readme  

This sample illustrates how to implement federated authentication using ACS and an Active Directory Federation Services (AD FS) 2.0 identity provider with a WCF relying party web service. The sample includes a WCF service and a WCF client as command line applications. The WCF service requires that clients authentication using a SAML token from ACS, which is obtained via another SAML token acquired from an AD FS 2.0 identity provider. The web service client requests a SAML token from AD FS 2.0 using Windows Authentication, and then exchanges this token for the ACS token required to access the WCF service. The code for this sample is in the Acs2FederationSample folder of the ACS 2.0 samples package.

Prerequisites 

To run this sample, you will need:

See Prerequisites for more details. Note that it may be beneficial to walkthrough the Getting Started sample before running this sample.

Configuring the Sample

The ACS configuration required for this sample can be performing using either the ACS management portal, or the ACS management service.   Select one of the two options below to go to the relevant section.

Note that since the sample uses AD FS 2.0 as the federation server, AD FS 2.0 must be installed and running. For more information about installing AD FS 2.0, see http://technet.microsoft.com/en-us/library/dd807086(WS.10).aspx

Option 1: Configuring via the ACS Management Portal 

 

1. Open a browser and navigate to http://windows.azure.com and sign in. From there, navigate to the Service Bus, Access Control, and Caching section to configure your ACS service namespace. Once you have created a namespace, select it and click Manage > Access Control Service at the top of the page. This should launch the following page in a new window:

 

2. Next, add your AD FS 2.0 identity provider. To do this, you will need to have your WS-Federation metadata document, which is hosted in your AD FS 2.0 server at /FederationMetadata/2007-06/FederationMetadata.xml. For example, if your AD FS 2.0 server is installed on a computer with the name contoso.com, then the metadata URL will be:

https://contoso.com/FederationMetadata/2007-06/FederationMetadata.xml

If the computer running AD FS 2.0 is accessible from internet and not placed behind a firewall, then you can use this URL directly. Otherwise, you will need to save this document to your computer and upload it to ACS when adding your identity provider.

3. Click Identity Provider in the left panel and then click Add.

 

4. Select WS-Federation identity provider and click Next. Depending on the Metadata document’s location, complete the form either entering the URL or using the saved file.

 

5. Next, register your application with ACS by creating a relying party application. Click the Relying Party Applications link on the main page, then click Add and enter the following information in the subsequent form.

  • In the Name field, enter "Federation Sample RP"
  • In the Realm field, enter http://localhost:7200/Service/Default.aspx 
  • In the Token format field, select SAML 2.0
  • In the Token encryption policy field, select "Require Encryption"
  • In the Identity Providers field, check only the AD FS 2.0 identity provider added in the previous step
  • For Token signing, select "Use a dedicated certificate". For the certificate file, browse for the ACS2SigningCertificate.pfx file in the Certificates folder of this sample. Enter a password of "password".
  • For the Token encryption certificate, browse for the WcfServiceCertificate.cer file in the Certificates folder of this sample and save the settings.

6. When complete, click the Save button and then navigate back to the main page.

  

7. With your relying party registered, it is now time to create the rules that determine the claims that ACS will issue to your application. To do this, navigate to the main portal page and select Rule Groups. From there, select the Default Rule Group for Federation Sample RP. Click Generate and then select AD FS 2.0 in the subsequent form:

Complete this form by clicking on the Generate button. This will create passthrough rules fo AD FS 2.0 based on the claim types present in the WS-Federation metadata.

8. Now it is time to add the decryption certificate. This certificate is needed for ACS to decrypt incoming tokens from the AD FS 2.0 identity provider. To do this, click Certificates and keys in the left panel, and click the Add link for Token Decryption.

9. In the Certificate field of the subsequent form, browse to Certificates folder of this sample and pick ACS2DecryptionCert.pfx. The password for this certificate is “password”.

 

10. Complete the form by clicking Save.

Option 2: Configuring via the ACS Management Service

The Visual Studio sample solution has a console application called ConfigureSample which uses the ACS Management Service and the common helpers defined in the Common class library. This application can be used to configure your ACS service namespace for use with this sample.

1. Update the Common class library with information about your Service Namespace. Open SamplesConfiguration.cs and enter your:

 

  • ServiceNamespace - This is the namespace used with ACS.
  • ManagementServiceIdentityName - This is a management service account’s Name
  • ManagementServiceIdentityKey - This is the password associated with the management service account.
  • AcsHostUrl - This is the host name of the ACS

 

2. Update the metadata related settings in Program.cs in ConfigureSample:

  • IdentityProviderMetadataUrl - This is the URL for the WS-Federation metadata of your AD FS 2.0. This setting can be found from the AD FS 2.0 console under “Service\Endpoints”.
  • entityId - This is the issuer name which ACS will use for your AD FS 2.0 identity provider. In the metadata document this is the entityID attribute’s value for the EntityDescriptor node.

3. Run the ConfigureSample application in Visual Studio, which will configure ACS to run this sample.

Configuring AD FS 2.0

Now with ACS configured, we need to configure the AD FS 2.0 end points to allow mixed-mode windows authentication and create a relying party trust with ACS.

1. In Windows Server, start the AD FS 2.0 management console by running the AD FS 2.0 Management application.

2. Expand Service and select Endpoints. Right-click the /adfs/services/trust/13/windowsmixed endpoint and enable it to enable windows mixed authentication mode.

 

3. Restart the AD FS 2.0 service. This can be done by calling the following command from an elevated command prompt:

net stop adfssrv && net start adfssrv

 

4. Now we need to add the relying party trust for the ACS. Right click on Relying Party Trusts and click on Add Relying Party Trust.

 

 

5. In this wizard, you will enter your Federation metadata for ACS which is located at https://<your namespace>.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml. Note that this information can be also found in the “Application Integration” page of the ACS Management Portal.

6. Enter a display name, select Permit all users to access to this relying party, and select Open the Edit Claim Rules dialog to open the rule editor.

7. In the rule editor select Add Rule…, click Next, and enter the following information:

  • Enter a display name for the rule
  • For Attribute store, select “Active Directory”
  • For the LDAP Attribute, select “E-Mail-Addresses”
  • For the Outgoing Claim Type, select “E-Mail Addresses”

8. Click Finish to complete the wizard.

Running the Sample

1. Open the sample in Visual Studio. The solution consists of two main projects: WcfService and WcfClient.

2. If you did not do so during configuration, enter your Service Namespace details in Common\SamplesConfiguration.cs. See step 1 of “Option 2: Configuring via the ACS Management Service” above. This file is also used by the WcfService and WcfClient projects.

3. Open the App.config in the WcfClient project

4. Enter your IdpEndpointAddress under the AppSettings element. You can get this information from your AD FS 2.0 endpoint settings. Typically this address will be https://<your-server>/adfs/services/trust/13/windowsmixed. Below is a code snippet showing this area of the Client App.config file. 
   

<appSettings>

   <!-- Idp configuration 

         This configuration depends on the idp binding used -->

   <add key="IdpEndpointAddress" value="https://contoso.com/adfs/services/trust/13/windowsmixed"/>

      <!-- Service configuration -->

   <add key="ServiceAddress" value="http://localhost:7200/Service/Default.aspx"/>

   <add key="ServiceCertificateFilePath" value="..\..\..\Certificates\WcfServiceCertificate.cer"/>

</appSettings>


 

5. Similar to Step 3, open App.config in WcfService project and set your IdpEndpointAddress with the same value used in Step 3. E.g:

<appSettings>

   <!-- ACS v2 configuration -->

   <add key="AccessControlSigningCertificateFilePath" value="..\..\..\Certificates\ACS2SigningCertificate.cer"/>

   <!-- Idp configuration 

         This configuration depends on the idp binding used -->

   <add key="IdpEndpointAddress" value="https://contoso.com/adfs/services/trust/13/windowsmixed"/>   

   <!-- Service configuration -->

   <add key="ServiceAddress" value="http://localhost:7200/Service/Default.aspx"/>

   <add key="ServiceCertificateFilePath" value="..\..\..\Certificates\WcfServiceCertificate.pfx"/>

   <add key="ServiceCertificatePassword" value="password"/>

</appSettings>
  
6. Last, but not least, it is time to run the sample! Start the WcfService, then start the WcfClient. At the client, enter a string to reverse. After entering that information, the Client console window should show output similar to the following:

 

 

 

 

 

Last edited Apr 9, 2011 at 1:01 AM by oremel, version 10

Comments

krist00fer Oct 13, 2011 at 11:25 AM 
Warning! Certificates Expired - According to the documentation found here http://msdn.microsoft.com/en-us/library/hh204521.aspx you will get an ACS50005 "Token encryption is required but no encrypting certificate is configured for the relying party." In the sample, the certificates ACS2SigningCertificate and WCFService Certificate has expired and therefore you'll get that error if you follow the example. Please generate your new certificates using the instructions found here http://msdn.microsoft.com/en-us/library/gg185932.aspx

Moox Jun 10, 2011 at 5:10 PM 
I keep getting this error: "Secure channel cannot be opened because security negotiation with the remote endpoint has failed. This may be due to absent or incorrectly specified EndpointIdentity in the EndpointAddress used to create the channel. Please verify the EndpointIdentity specified or implied by the EndpointAddress correctly identifies the remote endpoint."
Has anyone had this problem? Any fix?

kesarisuresh May 27, 2011 at 6:45 AM 
Very nice article. Can we also have a sample demostrating the same functionality using configuration information instead of writing code for configurations.

clamont May 10, 2011 at 3:35 PM 
This appears to use Windows integrated (Kerberos / NTLM) for authentication. What else needs to be done to use Username/Password or Certificates with ADFS + ACS?

clamont May 10, 2011 at 3:33 PM 
The ACS endpoint v2/wstrust/13/issuedtoken-symmetric doesn't appear on the Development/Application Integration tab of ACS manager. What other "hidden" endpoints exist. OAuth is another example of the same "hidden" functionality.