Azure AppFabric ACS Authentication (Portals 5.0)

This article covers the steps for enabling Windows Azure AppFabric Access Control Service (ACS) federated authentication for an Adxstudio portal. The first step involves configuring ACS on Windows Azure. The next step involves taking settings from the first step and applying them to the ASP.Net portal configuration.

A Windows Azure platform subscription should be available which provides access to the Azure Management Portal. The ASP.Net portal can be hosted from Windows Azure Hosted Services or on-premises from an IIS 7.0 server running .Net Framework 4.0 and Windows Identity Foundation (WIF).

A Service Namespace is required to contain the authentication settings.

• Sign into the Azure Management Portal
• Browse over to the "Access Control" table
  • Bottom left: Click Service Bus, Access Control & Caching
  • Top Left: Click Access Control
• Select the subscription that contains the ACS namespace
• Click New to open the new ACS namespace dialog
• Specify an available namespace ensuring that "Access Control" service is selected
• Click Create Namespace

• The new namespace should appear in the table
• Select the namespace
• Click the Access Control Service button to open the ACS Management Portal

The ACS based federated authentication settings are managed under this area of the portal. The two major steps to completing these settings are to select Identity Providers and specifying Relying Party Applications.

Identity providers decide which user accounts are available for authentication. By default, the Windows Live ID identity provider is available which allows authentication by Live ID users.

• Click the Add link to select a new identity provider
• Some providers only require a display name as a label for authenticating users
• Other providers require further credentials to be established between the identity provider and ACS. Refer to the Learn more links for details.
• Repeat this step for each identity provider you wish to make available

At least one relying party application must be setup for federated authentication to succeed. Navigate to the Relying Party applications area and click the "Add" link.

On the Add Relying Party Application page provide a display Name that identifies the relying party. Note that this name may also appear to the end user during sign-in depending on the implementation of the portal's sign-in page.

Under the Realm field, specify the domain URL of the portal. Valid URLS include:

• http://localhost/
• http://localhost:8080/
• http://contoso.com/
• https://contoso.com/

Authentication against ACS will fail if the portal is not hosted from this URL. It is not necessary for the portal to be available to the Internet.

For the Return URL, specify the realm URL and append a path of /Federation.axd.

• http://localhost/Federation.axd

If you are hosting one of the Adxstudio sample portals, there is an error web page page that is available that can be sepecified as the Error URL.

• http://localhost/error/

For the Token format, specify SAML 2.0. The Token encryption policy can be set to None and the Token lifetime can be left at the default of 600 seconds.

Under the Identity Providers section, check the providers that are allowed to authenticate.

If this is the first relying party application, check the box to Create new rule group which creates a default rule group when saved. Subsequent relying party applications may share this default rule group rather than creating a new one.

Under the Token signing section, specify Use service namespace certificate (standard).

Click Save.

This step may be repeated to add more relying party applications. This enables a single sign-on experience between all the relying party portals.

If a new rule group was created as a part adding a new relying party, then rules need to be created for the group. Navigate to the Rule Groups area and select the Default Rule Group.

Click the Generate link to add the default rules.

Finally, click the Generate button to create rules for every identity provider.

At this point, the required ACS management settings are complete and several values need to be applied to the ASP.Net portal. Take note of the following settings:

• Record the Service Namespace value
• Under Trust relationships -> Relying Party application, open the relying party details, record the Realm URI
• Under Service settings -> Certificates and keys -> Token Signing, open the Service Namespace for the x.509 Certificate. Under the Certificate section, record the thumbprint
• Under Development -> Application integration -> Endpoint Reference, record the WS-Federation Metadata
• The Thumbprint value of the cookie encryption certificate. This is required to maintain cookie consistency in web farm environments or Azure services configured with multiple instances. If omitted, Windows Data Protection (DPAPI) is used to protect session cookies. 

Portal configuration involves taking the values collected from the ACS Management Portal and applying them to the web.config file of the portal. This will be demonstrated against the Adxstudio sample portals.

• Browse to the folder containing the Adxstudio sample portals:
  • %adxstudio install root%\XrmPortals\4.1.xxxx\Samples\
• Open the XrmSamples.sln solution in Visual Studio 2010
• In the Solution Explorer, select a portal to deploy such as the BasicPortal
• Open the Web.ACS.config web config transform file (expand the Web.config node)
• Replace the placeholder values within the Web.ACS.config file with the values gathered in the previous step

The following is a condensed form of the Web.ACS.config file to help locate the relevant configuration attributes that need to be updated.

<configuration>
  <appSettings>
    <add key="FederationMetadataLocation" value="[WS-Federation Metadata]"/>
  </appSettings>
  <microsoft.identityModel>
    <service>
      <audienceUris>
        <add value="[Realm URI]" />
      </audienceUris>
      <federatedAuthentication>
        <wsFederation
          issuer="https://[Service Namespace].accesscontrol.windows.net/v2/wsfederation" realm="[Realm URI]"/>
      </federatedAuthentication>
      <issuerNameRegistry>
        <trustedIssuers>
          <add thumbprint="[Thumbprint]" name="https://[Service Namespace].accesscontrol.windows.net/" />
        </trustedIssuers>
      </issuerNameRegistry>
      <serviceCertificate>
        <certificateReference x509FindType="FindByThumbprint" findValue="[Cookie Encrpytion Certificate Thumbprint]"/>
      </serviceCertificate>
      <certificateValidation certificateValidationMode="None"/>
    </service>
  </microsoft.identityModel>
</configuration>

After transformation, the resulting Web.config will contain the following federated identity related configuration elements.

<configuration>
  <configSections>
    <section name="microsoft.identityModel"
      type="Microsoft.IdentityModel.Configuration.MicrosoftIdentityModelSection, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <section name="microsoft.xrm.portal.identityModel"
      type="Microsoft.Xrm.Portal.IdentityModel.Configuration.IdentityModelSection, Microsoft.Xrm.Portal" />
  </configSections>
  <appSettings>
    <add key="FederationMetadataLocation" value="[WS-Federation Metadata]" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <httpRuntime
      requestValidationType="Microsoft.Xrm.Portal.IdentityModel.Web.FederationRequestValidator, Microsoft.Xrm.Portal" />
    <pages viewStateEncryptionMode="Always" validateRequest="true">
      <controls>
        <add tagPrefix="wif" namespace="Microsoft.IdentityModel.Web.Controls"
          assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </controls>
    </pages>
    <httpModules>
      <add name="SessionAuthenticationModule"
        type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
    </httpModules>
    <httpHandlers>
      <add path="LiveID.axd" verb="*"
        type="Microsoft.Xrm.Portal.IdentityModel.Web.Handlers.LiveIdAccountTransferHandler, Microsoft.Xrm.Portal"/>
      <add path="Federation.axd" verb="*"
        type="Microsoft.Xrm.Portal.IdentityModel.Web.Handlers.FederationAuthenticationHandler, Microsoft.Xrm.Portal"/>
    </httpHandlers>
  </system.web>
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="SessionAuthenticationModule"
        type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
        preCondition="managedHandler"/>
    </modules>
    <handlers>
      <add name="LiveId" verb="*" path="LiveID.axd" preCondition="integratedMode"
        type="Microsoft.Xrm.Portal.IdentityModel.Web.Handlers.LiveIdAccountTransferHandler, Microsoft.Xrm.Portal"/>
      <add name="Federation" verb="*" path="Federation.axd" preCondition="integratedMode"
        type="Microsoft.Xrm.Portal.IdentityModel.Web.Handlers.FederationAuthenticationHandler, Microsoft.Xrm.Portal"/>
    </handlers>
  </system.webServer>
  <microsoft.identityModel>
    <service>
      <audienceUris>
        <add value="[Realm URI]" />
      </audienceUris>
      <federatedAuthentication>
        <wsFederation
          issuer="https://[Service Namespace].accesscontrol.windows.net/v2/wsfederation" realm="[Realm URI]"/>
      </federatedAuthentication>
      <issuerNameRegistry>
        <trustedIssuers>
          <add thumbprint="[Thumbprint]" name="https://[Service Namespace].accesscontrol.windows.net/" />
        </trustedIssuers>
      </issuerNameRegistry>
      <serviceCertificate>
        <certificateReference x509FindType="FindByThumbprint" findValue="[Cookie Encrpytion Certificate Thumbprint]" />
      </serviceCertificate>
      <certificateValidation certificateValidationMode="None" />
    </service>
  </microsoft.identityModel>
  <microsoft.xrm.portal.identityModel>
    <registration
      enabled="true"
      registrationPath="~/register/"
      profilePath="~/profile/"
      accountTransferPath="~/account-transfer/"
      requiresInvitation="true"
      requiresChallengeAnswer="true"
      requiresConfirmation="false"
      invitationCodeDuration="01:00:00"/>
  </microsoft.xrm.portal.identityModel>
</configuration>

As with any Adxstudio Portal, the connection string needs to be updated to specify a valid Microsoft Dynamics CRM 2011 server. For details refer to this article.

The Web.ACS.config file is a transformation file used to convert a sample portal running against a MembershipProvider into a portal that supports ACS federated authentication.

The XrmSamples.sln solution already contains the build configuration needed to apply this transform during deployment. With this solution still open in VS2010, go to the menu -> Build -> Configuration Manager.... Within the Configuration Manager dialog, use the Active solution configuration dropdown to select the ACS option. Each portal that is capable of an ACS transform, should show a value of ACS under the Configuration column. Close the Configuration Manager.

Return to the Solution Explorer and right-click the portal project. Select Publish... to open the Publish Web dialog. Check that the Build Configuration value indicates "ACS". Select a Publish method such as "File System" and set a Target Location to be the Physical Path of the IIS website or web application that is hosting the portal (this should initally be an empty folder). Click Publish to transform the web.config and copy the portal files to the Target Location.

Create a website or web application specifying the Physical Path to be the published Target Location. The website should also specify the Realm URI value as its site binding setting.

In a web browser, open the Realm URI to navigate to the website. Click the Login link to open the portal's identity provider selection page. If the configuration is correct, a module should appear in the body of the page allowing the user to select from the configured identity providers.