Export (0) Print
Expand All

Authenticate the user with the web services

Applies To: Microsoft Dynamics CRM 2013, Microsoft Dynamics CRM Online

You can use the external client authentication capability of Microsoft Dynamics CRM to develop your own client apps for mobile devices, such as tablets and phones, as well as for the Windows 8 desktop. This capability is also available to non-.NET applications.

Overview of authentication

Developers who create modern and mobile apps, including apps not built on the .NET Framework, can access Microsoft Dynamics CRM business data through the SOAP and OData endpoints of the organization web service. This web service supports certain authentication capabilities found in the OAuth 2.0 protocol.

The following list describes what is supported for modern and mobile app authentication:

  • Use of JSON web tokens in the HTTP authorization header

  • Authentication for the OData service by external apps (outside the browser)

  • Authentication for the Organization.svc/web (SOAP) service by external applications (outside the browser)

Technology dependencies

The following technology is required to develop and execute external client applications that authenticate with the Microsoft Dynamics CRM OData and SOAP web service endpoints:

The following technology is optional to develop and execute external client applications that authenticate with the Microsoft Dynamics CRM OData and SOAP web service endpoints:


The following security information applies to this authentication feature:

  • The authentication token is stored on the device in protected storage. For the Windows operating system, the Windows Credential Manager is used.

  • The feature makes use of Secure Sockets Layer (SSL) for HTTP requests.

User sign-in and application registration

The following information is related to user sign-in and application registration.

  • User sign-in for the Microsoft Azure Active Directory Authentication Library (ADAL) is handled by a web browser context.

  • Application registration is managed through Azure Active Directory for a CRM Online deployment, and Active Directory Federation Services (AD FS) for on-premises or Internet-facing deployment (IFD). You can use the Microsoft Azure management portal or API to register your app with CRM Online.

The client application

The range of operations that an external client application can perform is summarized in the following list:

  • When using the OData endpoint, Create, Retrieve, Update, and Delete operations are supported. There is no support for message execution or metadata retrieval.

  • When using the SOAP endpoint (Organization.svc/web) for modern and mobile applications, access to the full web service feature set is available.

When writing client code that makes calls to the web service it is a best practice recommendation to request a token through ADAL before every service call.  That way ADAL can determine whether it can re-use a cached instance of the access token, make a request for a new one using the refresh token, or prompt the user for sign-on.

Discover the OAuth endpoint URL

The ability to discovery the authority for web service authentication at run-time is provided as an alternate method to obtain the authority as compared to hardcoding OAuth provider URLs in applications or configuration files. This feature is provided in Microsoft Dynamics CRM Online Spring ‘14 and Microsoft Dynamics CRM 2013 Service Pack 1.

The discovery process is started by sending an unauthorized HTTP request with the word “Bearer” in the Authorization header and the tenant organization’s SOAP endpoint URL as the request message.

GET /XRMServices/2011/Organization.svc HTTP/1.1
Host: <org>.crm.dynamics.com
Authorization: Bearer

A 401 error is returned with a response containing an authorization_uri parameter. That value of that parameter is an authority URL.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri=URI

The authority discovery feature is made available to clients only when an SdkClientVersion property is present in the tenant organization’s SOAP endpoint URL. An example URL is shown below.


The SdkClientVersion value can be any version number than has at least one decimal point and is greater than 6.0.0002.0000. It’s recommended that the SdkClientVersion property value be set to the product build version of the SDK assemblies that were linked to the client application.

The following code sample demonstrates how to obtain the authority URL. Note that the sample code makes use of the Microsoft Azure Active Directory Authentication Library (ADAL), which can be obtained from NuGet.org. There are also open sourced versions of this library for Android and iOS.

/// <summary>
/// Discover the authority for authentication.
/// </summary>
/// <param name="serviceUrl">The SOAP endpoint for a tenant organization.</param>
/// <returns>The decoded authority URL.</returns>
/// <remarks>The passed service URL string must contain the SdkClientVersion property.
/// Otherwise, the discovery feature will not be available.</remarks>
public String DiscoveryAuthority(Uri serviceUrl)
    // Use AuthenticationParameters to send a request to the organization's endpoint and
    // receive tenant information in the 401 challenge. 
    AuthenticationParameters parameters = null;

    HttpWebResponse response = null;
        // Create a web request where the authorization header contains the word "Bearer".
        HttpWebRequest httpWebRequest = (HttpWebRequest) WebRequest.Create(serviceUrl);
        httpWebRequest.Headers.Add(HttpRequestHeader.Authorization.ToString(), "Bearer");

        // The response is to be encoded.
        httpWebRequest.ContentType = "application/x-www-form-urlencoded";
        response = (HttpWebResponse) httpWebRequest.GetResponse();

        // If the expected response is returned, this code should not execute.
        throw new ActiveDirectoryAuthenticationException("unauthorized_response_expected",
            "Unauthorized http response (status code 401) was expected");
    catch (WebException ex)
        response = (HttpWebResponse) ex.Response;
        if (response == null)
            throw new ActiveDirectoryAuthenticationException(
                "Unauthorized Http Status Code (401) was expected in the response",
                (Exception) ex);

            // A good response was returned. Extract any parameters from the response.
            // The response should contain an authorization_uri parameter.
            parameters = AuthenticationParameters.CreateFromUnauthorizedResponse(response);
        if (response != null)

    // Return the authority URL.
    return parameters.Authority;

OAuth authorization endpoints

An alternative method to using OAuth discovery is to use well known OAuth authorization endpoints. When writing an app that authenticates with the Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online web services, you need to use the OAuth provider URLs in your authentication code, as shown in the following table.


Deployment URL

Microsoft Dynamics CRM Online


https://login.windows.net/<tenant ID>/oauth2/authorize

Microsoft Dynamics CRM 2013 (on-premises/IFD)


Substitute the address of your IFD server, for example contoso.com, in the security token service (STS) URL. The STS URL shown is for the default installation of AD FS. A non-default installation may use a different URL. Similarly, substitute your tenant ID where indicated.

It’s recommended that you always use OAuth discovery with CRM Online since the authorization endpoints can change at some future time.

Specify an OAuth resource

When authenticating with Microsoft Azure Active Directory using the OAuth authorization code flow, you must provide a value for the target resource. The root organization web address, for example: https://contoso.crm.dynamics.com, needs to be used as the “resource” query string parameter in the call to the OAuth authorization endpoint.

// Obtain an authentication token to access the web service.
String resource = “https://contoso.crm.dynamics.com”; 
_authenticationContext = new AuthenticationContext(_oauthUrl, false );
AuthenticationResult result = await _authenticationContext.AcquireTokenAsync( resource, clientID );

More information: Sample: Windows 8 desktop modern OData app

See Also

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