Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Active Directory and Claims-Based Authentication

[Applies to: Microsoft Dynamics CRM 2011]

Claims-based authentication provides an industry standard security protocol to authenticate a user on a host computer. Claims-based authentication is a set of WS-* standards describing the use of a Security Assertion Markup Language (SAML) token in either passive mode (when WS-Federation is used with the Microsoft Dynamics CRM 2011 web application) or active mode (where WS-Trust in used with Windows Communication Foundation (WCF) clients). This authentication works together with WCF to provide secure user authentication and a communication channel with a Microsoft Dynamics CRM server. All Microsoft Dynamics CRM editions support claims-based authentication.

Claims-based authentication requires the availability of a security token service (STS) running on a server. An STS server can be based on Active Directory Federation Services (AD FS) V2, or any platform that provides the official STS protocol. For more information, see the following topics in the Microsoft Dynamics CRM 2011 Implementation Guide:

To access a claims configured Microsoft Dynamics CRM 2011 or Microsoft Dynamics CRM Online server by using the Microsoft Dynamics CRM SDK methods, you must first install Windows Identity Foundation (WIF) on your development computer. The Windows Identity Foundation download installs the Microsoft.IdentityModel.dll assembly, which is referenced by the Microsoft Dynamics CRM SDK assemblies at run time. This requirement applies only to code built using Microsoft .NET Framework 4. Microsoft .NET Framework 4.5 includes the required identity namespace.

If your organization has been updated to Microsoft Dynamics CRM Online Fall ’13, please use the latest version of the SDK. Download the updated SDK package for Microsoft Dynamics CRM 2013 and CRM Online Fall ‘13.

In this Section

Supported Authentication Scenarios

Microsoft Dynamics CRM supports the following authentication scenarios for each deployment type.


Deployment Authentication model

Microsoft Dynamics CRM Online

Claims-based or Active Directory (through federation) authentication

Microsoft Dynamics CRM 2011 on-premises

Claims-based or Active Directory authentication

Microsoft Dynamics CRM 2011 Internet-facing deployment (IFD)

Claims-based or Active Directory authentication

How Claims-based Authentication Works

A request to authenticate a user is sent from Microsoft Dynamics CRM 2011 or Microsoft Dynamics CRM Online or a custom application to the STS server. The STS server determines whether the user should be authenticated, and if so, issues a signed and encrypted SAML token that contains user authentication information. The token has a finite life span and may have to be periodically refreshed depending on how long your application is using the token. This is discussed in more detail later in this topic.

How Active Directory Authentication Works

A request to authenticate a user is sent from Microsoft Dynamics CRM or a custom application to Active Directory. The WCF stack manages the authentication process for Microsoft Dynamics CRM SDK API calls from an application, whereas Internet Information Services (IIS) manages authentication for a web application.

Unsupported Authentication Scenarios

Use of client certificates is not supported by the Microsoft Dynamics CRM SDK. If you configure the Microsoft Dynamics CRM website to require IIS client certificates, you will get authentication failures for any applications that were built using the SDK.

For more information about additional unsupported programming methods see Unsupported Customizations.

Authentication Classes

The following table lists the primary authentication classes available in the SDK, describes when to use them, and provides links to additional relevant documentation.


Classes Usage Related Documentation

IServiceConfiguration, IServiceManagement

All deployment types: on-premises/IFD, online (Microsoft account and Office 365/MOS*)

Authenticate Office 365 Users with Microsoft Dynamics CRM Online Web Services

Sample: Authenticate Users with Microsoft Dynamics CRM Web Services

DiscoveryServiceProxy, OrganizationServiceProxy

All deployment types: on-premises/IFD, online (Microsoft account and Office 365/MOS*)

Authentication by Using the Client Proxy Classes

Sample: Access the Discovery Service

Improve Service Channel Allocation Performance


All deployment types: on-premises/IFD, online (Microsoft account and Office 365/MOS*)

Simplified Connection to Microsoft Dynamics CRM

Sample: Simplified Connection Quick Start using Microsoft Dynamics CRM


All deployment types: on-premises/IFD, online (Microsoft account and Office 365/MOS*)

Use for console test applications and sample code.

Designed to improve usability when running SDK sample code and to demonstrate use of the authentication classes. Contains console output code.

Helper Code: ServerConnection Class

Sample: Quick Start for Microsoft Dynamics CRM

* Microsoft online services environment

Authentication by Using the Client Proxy Classes

One way to authenticate with the Microsoft Dynamics CRM web services is by using the OrganizationServiceProxy and DiscoveryServiceProxy classes in the applications that you write. These proxy classes automatically handle claims or Active Directory authentication and also manage resource limits on the WCF channel endpoint.

The following code shows how to instantiate the organization service proxy:

using (OrganizationServiceProxy _serviceProxy = new OrganizationServiceProxy(organizationUri, homeRealmUri,
    userCredentials, deviceCredentials))

The following code shows how to instantiate the discovery service proxy:

using (DiscoveryServiceProxy _discProxy = new DiscoveryServiceProxy(discoveryUri, homeRealmUri,
    userCredentials, deviceCredentials))

It is important to properly dispose of the service proxy instance in your application before the application terminates. The using statement makes sure that the service proxy is correctly disposed by automatically calling Dispose on the service proxy when it goes out of scope. However, for improved application performance, it is a best practice to keep the service proxy instance available in your application for the entire application session instead of disposing it and allocating it again somewhere else in the application code when needed. The reason being that creating and authenticating a service channel is an expensive operation (in time). In this case, when you are done with the service proxy instance, you must directly call the Dispose method on the proxy before the application terminates.

The device credentials of the registered computing device are only used when authenticating with the Microsoft account identity provider of Microsoft Dynamics CRM Online. For sample code that shows how to populate the proxy constructor parameters, see Sample: Access the Discovery Service.

For an on-premises or an Internet-facing deployment (IFD) installation of Microsoft Dynamics CRM 2011, the client proxy classes use claims-based authentication if an STS server is available. Otherwise, Active Directory authentication is used.

If you want to use Microsoft Dynamics CRM early-bound entity types in your code, you must add the following line of code after the organization service proxy is instantiated, but before you make web service method calls:


securitySecurity Note
WCF supports a feature where it can interactively prompt the user for logon credentials when it is necessary. This feature is enabled by setting the SupportInteractive property of the ClientCredentials class. These credentials are used in the userCredentials parameter shown in the previous code snippet.

When making SDK calls to the Microsoft Dynamics CRM web services, the ownership of the operation and entity data changes performed by the SDK call can be changed by this WCF feature independent of your code.

Microsoft Dynamics CRM handles supplied credentials in web service calls as follows:

  • If credentials are not supplied in the web service call, the WCF stack determines which credentials to use. In that case, the SupportInteractive property value is automatically set to false.

  • If credentials are explicitly supplied by your code, the current SupportInteractive value is passed to the WCF channel factory. SupportInteractive is set to true by default unless you explicitly change it.

  • If SupportInteractive is set to true and the provided credentials fail, a WCF dialog box may be displayed. Any credentials entered by the user into the dialog box will be used instead of those supplied in the web service calls that your application invokes.

Handling Channel Exceptions and Faults

Your code should catch the following exceptions and faults. See the C# or Microsoft Visual Basic .NET samples in the Microsoft Dynamics CRM SDK for a list of additional exceptions to catch:

For more information, see the .NET Framework WCF documentation about how to handle WCF faults and exceptions. See Use the Sample and Helper Code for additional sample code.

Additional Information About The Security (SAML) Token

The SAML token replaces the Microsoft account and discovery web service tickets that were used to authenticate a user in Microsoft Dynamics CRM 4.0 and previous releases of Microsoft Dynamics CRM Online.

Contents of the SAML Token

The XML-based SAML 2.0 token contains an identity that defines one or more claims about a user. This token is passed between an identity provider (STS) server and Microsoft Dynamics CRM for claims-based authentication. The claims in the identity have been defined as follows.


Claim Use

Universal Principal Name (UPN)

Contains the user’s ID in domain\alias format on the target Microsoft Dynamics CRM server.


If the authenticated user is also a Deployment Administrator in Microsoft Dynamics CRM, this claim contains the deployment administrator’s ID in domain\alias format on the target Microsoft Dynamics CRM server. Windows Identity Foundation maps the Name claim to the Identity.name property.

Any other claims

Not used by Microsoft Dynamics CRM.

Supported Security Token Types

Microsoft Dynamics CRM 2011 support two types of SAML tokens:

  • Web application - The Microsoft Dynamics CRM web application receives a bearer token from STS. This token is missing some required information so a Secure Sockets Layer (SSL)-based URL (https://) is used for security protection when you access the WCF endpoint.

  • SDK - A custom application receives an active token with a proof key that contains the required information.

Lifecycle of the Security Token

A SecurityToken has a life span identified by its ValidFrom and ValidTo properties. Your application design should consider the possibility that the token could expire, resulting in an ExpiredSecurityTokenException being thrown by the Microsoft Dynamics CRM web services when the next message request from your application is processed.

For sample code that demonstrates how to refresh a security token, see the AutoRefreshSecurityToken.cs and ToolServiceProxies.cs files in the SDK\Tools\PluginRegistration folder of the SDK download.

See Also

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

© 2014 Microsoft. All rights reserved.