Authenticate the user with the web services

 

Applies To: Dynamics CRM 2013

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.

In This Topic

Overview of authentication

Technology dependencies

Security

User sign-in and application registration

The client application

OAuth authorization endpoints

Discover the OAuth endpoint URL

Specify an OAuth resource

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:

• Claims configuration is required for on-premises deployment.

• AD FS on Windows Server 2012 R2.

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:

•  Microsoft Azure Active Directory Authentication Library (ADAL)

  • Microsoft Azure AD Authentication Library for .NET

  • Microsoft Azure AD Authentication Library for iOS

  • Microsoft Azure AD Authentication Library for Android

• Visual Studio 2012 or 2013

Security

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 you write client code that makes calls to the web service, it’s recommended to request a token through ADAL before every service call. That way, ADAL can determine whether to reuse a cached instance of the access token, make a request for a new one using the refresh token, or prompt the user to sign in.

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 (SP1).

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.

https://contoso.crm.dynamics.com/XRMServices/2011/Organization.svc/web?SdkClientVersion=6.1.0.533;

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;
    try
    {
        // 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);
        }
        else
        {

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

    // 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/common/oauth2/authorize https://login.windows.net/<tenant ID>/oauth2/authorize
Microsoft Dynamics CRM 2013 (on-premises/IFD)	https://<serverFQDNaddress>/adfs/ls/XRMServices/2011/Organization.svc/web

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

Write mobile and modern apps
Walkthrough: Register a CRM app with Active Directory
Authenticate users with Microsoft Dynamics CRM 2013 web services
Blog: Introducing a New Capability in the Azure AD Developer Preview: the Azure Authentication Library