Authenticate the user with the web services

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can use the external client authentication capability of Microsoft Dynamics 365 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 365 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 365OData and SOAP web service endpoints:

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

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 Transport Layer Security (TLS) or 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 Dynamics 365 (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 Dynamics 365 (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’s recommended 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 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.

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

Note

The bearer challenge is now optional. Doing a GET without an authorization header yields the same results.

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 SOAP 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 authentication authority.
/// </summary>
/// <param name="serviceUrl">The URL of the organization's SOAP endpoint. </param>
/// <returns>The authority URL.</returns>
/// <remarks>The service URL must contain the SdkClient property.</remarks>
/// <example>https://contoso.crm.dynamics.com/XRMServices/2011/Organization.svc/web?SdkClientVersion=6.1.0.533;</example>
public static string DiscoveryAuthority(Uri serviceUrl)
{
    // Use AuthenticationParameters to send a request to the organization's endpoint and
    // receive tenant information in the 401 challenge. 
    Microsoft.IdentityModel.Clients.ActiveDirectory.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);

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

    catch (WebException ex)
    {
        response = (HttpWebResponse)ex.Response;

        // A 401 error should be returned. Extract any parameters from the response.
        // The response should contain an authorization_uri parameter.
        parameters = Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationParameters.
            CreateFromResponseAuthenticateHeader((response.Headers)["WWW-Authenticate"]);
    }
    finally
    {
        if (response != null)
            response.Dispose();
    }
    // 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 365 (online & on-premises) web services, you need to use the OAuth provider URLs in your authentication code, as shown in the following table.

Deployment

URL

Microsoft Dynamics 365 (online)

HYPERLINK "https://login.windows.net/common/oauth2/authorize" https://login.windows.net/common/oauth2/authorize (multi-tenant)

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

Microsoft Dynamics 365 (on-premises/IFD)

https://<serverFQDNaddress>/adfs/ls

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 Dynamics 365 (online) since the authorization endpoints can change at some future time.

Specify an OAuth resource

When authenticating with Microsoft AzureActive 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 Dynamics 365 app with Active Directory
Authenticate users in Microsoft Dynamics 365
Blog: Introducing a New Capability in the Azure AD Developer Preview: the Azure Authentication Library
Server-side CRM authentication using Azure Active Directory

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright