Walkthrough: Single Sign-on from a Custom Web Page

  • Article

[Applies to: Microsoft Dynamics CRM 2011]

This walkthrough and the accompanying sample code demonstrate how to write a custom webpage, named Default.aspx, that makes Microsoft Dynamics CRM SDK method calls on behalf of the logged-on user. When displayed, the sample webpage obtains information from Microsoft Dynamics CRM about the logged-on user and displays it. A Microsoft Dynamics CRM Internet-facing deployment (IFD) is used for this example.

For information about implementing a single sign-on web page in an IFRAME of the Microsoft Dynamics CRM Online web application, see Implement Single Sign-on from an ASPX Webpage or IFRAME.

Prerequisites

  1. Purchase or obtain a trusted encryption certificate.

  2. Install the Windows Identity Foundation SDK (version 4.0) on your development computer. If you are building your web application using Microsoft .NET Framework 4.5, you can skip this step.

  3. Set up a Microsoft Dynamics CRM 2011 IFD server configured for federated claims.

    For more information, see the Configure Microsoft Dynamics CRM for an Internet-Facing Deployment topic in the Microsoft Dynamics CRM 2011 Implementation Guide.

  4. Set up a security token service (STS) server running Active Directory Federation Services 2.0 where Microsoft Dynamics CRM 2011 is configured as a relying party.

    For more information, see the Configure the ADFS 2.0 server for IFD topic in the Implementation Guide.

  5. Create a service account on the Microsoft Dynamics CRM server.

    Note

    A service account is a system user account where the accessmode attribute is set to “Non-interactive”. For any Microsoft Dynamics CRM deployment, assign the service account the “Act On Behalf Of Another User” privilege or for on-premises deployments you can add the account to the Active Directory group named PrivUserGroup. It is this service account that performs the intended operation on behalf of the logged-on user. For more information about the SystemUser entity and the access mode, see User and Team Entities and SystemUser (User) Entity OptionSet Attribute Metadata. For detailed instructions on creating a service account, see Create a non-interactive user.

    The application pool account (CRMAppPool) used for the Microsoft Dynamics CRM web application should not be used as the service account. For more information, see Problems in CRM when the CRMAppPool user account is a CRM user.

    The following behavior applies to the service account depending on what security is used.

    • PrivUserGroup membership - Only the impersonated user’s privileges are checked when executing SDK method calls.

    • Act On Behalf Of Another User privilege - Both actors (caller and impersonated) are checked for the privileges that the SDK method call requires.

  6. Create a website to host the webpage. It can be a separate site on the Microsoft Dynamics CRM server or some other Internet Information Services (IIS) server.

Initial Sample Setup

Configure the sample by following these steps:

  1. Open the ExternalCRM.sln solution in Visual Studio 2010. The sample is located in the SampleCode\CS\GeneralProgramming\Authentication\IFDSingleSignOn folder of the SDK download.

  2. In Solution Explorer, add references for the Microsoft.Crm.Sdk.Proxy.dll and Microsoft.Xrm.Sdk.dll assemblies to the project. These assemblies are located in the SDK\bin folder.

  3. Right-click the project name in Solution Explorer and select Properties.

  4. Select the Web properties tab, select Use Custom Web Server, and enter the URL of your web server.

  5. Select the Package/Publish Web tab, and then enter a name for your website in the field labeled IIS Web site/application name to use on the destination server. Close the properties sheet.

  6. In Solution Explorer, right-click the project, and select Add STS reference.

Filling Out the STS Reference Wizard

Follow these steps to fill in the required wizard data:

  1. On the Welcome to the Federation Utility Wizard page, enter the application URI of the custom webpage, which is Default.aspx in the sample.

  2. On the Security Token Service page, select Use an existing STS, and then enter the location of the federated metadata document. Ask the person who set up your STS server for this information.

  3. On the STS signing certificate chain validation error page, make any appropriate choice.

  4. On the Security token encryption page, enable encryption. You must specify the same certificate that was used to configure Microsoft Dynamics CRM 2011 for IFD. The certificate should be installed on your development computer, the Microsoft Dynamics CRM 2011 server, and the IIS server that hosts the custom webpage. Of course, you can use just one computer for all three.

  5. On the Offered claims page, only name and roles claims are required.

Completing the Sample Setup

Follow these additional steps to complete setting up the sample:

  1. Edit the sample’s Web.config file. Uncomment the upn and name claimtype lines as shown here.

    <applicationService>
   <claimTypeRequired>
      <!--Following are the claims offered by STS 'http://adfs.smclaims02.com/adfs/services/trust'.-->
      <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" />
      <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" />
      <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />-->
      <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" optional="true" />-->
      <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" optional="true" />

  2. Within the <system.web> … </system.web> tags, add the following XML code.

    <httpModules>
  <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule,
 Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule,
 Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
</httpModules>

    Use the correct Version and PublicKeyToken values for the Microsoft.IdentityModel.dll assembly installed on your computer.

  3. In the code-behind page of Default.aspx, modify lines 26 through 30 as appropriate for your installation. You will need to provide the URL for the Microsoft Dynamics CRM organization and discovery services, and the service account’s user name and password.

  4. Publish the project by right-clicking the project name in Solution Explorer and then selecting Publish.

  5. On the STS server, make the Microsoft Dynamics CRM website and the sample’s website relying parties. You must use the same encryption certificate for both. For more information about configuring a relying party, see the Microsoft Dynamics CRM 2011 Implementation Guide documentation referenced previously. The FederationMetadata.xml file, which was generated by Visual Studio when the STS reference was added to the project, can be used in the STS Add Relying Party wizard.

  6. The certificate used to encrypt and sign the token in the Active Directory Federation Services (AD FS) server must be added to the “Trusted Root Certification Authorities” certificate store of the server that hosts your custom web application. You can do this using the certificate snap-in of the MMC (Microsoft Management Console).

  7. Optionally, add the Default.aspx webpage to an IFRAME in the Microsoft Dynamics CRM web application. When customizing the Microsoft Dynamics CRM webpage to add an IFRAME, clear the Restrict cross-frame scripting check box.

Running the Sample

Now that you have completed configuring and publishing, follow these steps to see the results:

  1. Log on to Microsoft Dynamics CRM.

  2. Navigate to the Default.aspx webpage.

You should see information about the logged-on user in the webpage.

See Also

Concepts

Implement Single Sign-on from an ASPX Webpage or IFRAME

Other Resources

Authenticate Users with Microsoft Dynamics CRM Web Services

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.