This documentation is archived and is not being maintained.

Client-to-Server Authentication

Dynamics
banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

A client application (console application, or a Windows Forms application) authenticates with Microsoft Dynamics CRM Online by using a Client-to-Server authentication process. The Client-to-Server authentication process with Microsoft Dynamics CRM Online is shown in the following figure.

Windows Live authentication

The Microsoft Dynamics CRM Online authentication process involves the following steps:

  • (1,2) Retrieve a policy from the CrmDiscoveryService Web service.
  • (3,4) Retrieve a Windows Live ticket.
  • (5,6) Retrieve information about the specified organization and a ticket from the CrmDiscoveryService Web service. The ticket applies to a single organization. The ticket contains an organization specific CrmService URL. Refer to the Active Directory authentication sample for additional sample code, which shows how to obtain organization information by using RetrieveOrganizationsRequest.
  • (7) Create an instance of the CrmAuthenticationToken class that has the CrmTicket and OrganizationName properties set to the correct values.
  • (7) Create an instance of the CrmService class that has the Url property value and the CrmAuthenticationTokenValue property value set.
  • (7) Invoke CrmService Web service methods.

Example

The following code sample shows you how to authenticate in Microsoft Dynamics CRM Online and call a CrmService method.

[C#]
using System;
using System.Xml;
using System.Text;
using System.Web.Services.Protocols;

// Microsoft Passport namespaces
using Microsoft.Crm.Passport.Sample;

namespace Microsoft.Crm.Sdk.Walkthrough
{
    // Import the Microsoft Dynamics CRM namespaces.
    using CrmSdk;
    using CrmSdk.Discovery;

    public class TimeoutSample
    {
        // Login information for authentication through the Windows Live service.
        static private string _username = "someone@microsoft.com";
        static private string _password = "password";
        static private string _partner = "crm.dynamics.com";
        static private string _environment = "Production";

        // Set the name and TCP port of the server hosting Microsoft Dynamics CRM Live.
        static private string _hostname = "dev.crm.dynamics.com";

        // Set the friendly name of the target organization.
        static private string _orgFriendlyName = "AdventureWorksCycle";

        // Define an expired authentication ticket error code.
        static private string EXPIRED_AUTH_TICKET = "8004A101";

        // Passport ticket required to recover from CrmTicket time out.
        static private string _passportTicket;

        // Attempt a service call a maximum number of times before failing.
        static private int MAX_RETRIES = 5;

        public static void InvokeServiceMethod(int retryCount)
        {
            try
            {
                if (retryCount == MAX_RETRIES)
                {
                    // Throw an exception when the maximum retry count is reached.  
                    throw new Exception("An error occurred while attempting to authenticate.");
                }
                else
                {
                    // STEP 1,2: Retrieve a policy from the Discovery Web service.
                    CrmDiscoveryService discoveryService = new CrmDiscoveryService();
                    discoveryService.Url = 
                        String.Format("https://{0}/MSCRMServices/2007/{1}/CrmDiscoveryService.asmx",
                        _hostname, "Passport");

                    RetrievePolicyRequest policyRequest = new RetrievePolicyRequest();
                    RetrievePolicyResponse policyResponse = 
                        (RetrievePolicyResponse)discoveryService.Execute(policyRequest);

                    // STEP 3,4: Retrieve a Passport ticket from the Windows Live service.
                    LogonManager lm = new LogonManager();
                    _passportTicket = lm.Logon(_username, _password, _partner, policyResponse.Policy,
                        _environment);

                    // Dispose of the LogonManager object to avoid a FileNotOpen exception.
                    lm.Dispose();

                    // STEP 5,6: Retrieve a target organization and a CrmTicket from the Discovery 
                    // Web service. Retrieve a list of organizations that the logged on user is a member of.
                    RetrieveOrganizationsRequest orgRequest = new RetrieveOrganizationsRequest();
                    orgRequest.PassportTicket = _passportTicket;
                    RetrieveOrganizationsResponse orgResponse =
                        (RetrieveOrganizationsResponse)discoveryService.Execute(orgRequest);
                    // Locate the target organization name using the organization friendly name.
                    String orgUniqueName = String.Empty;
                    OrganizationDetail orgInfo = null;
                    foreach (OrganizationDetail orgDetail in orgResponse.OrganizationDetails)
                    {
                        if (orgDetail.FriendlyName.Equals(_orgFriendlyName))
                        {
                            orgInfo = orgDetail;
                            orgUniqueName = orgInfo.OrganizationName;
                            break;
                        }
                    }
                    // Retrieve the CrmTicket.
                    RetrieveCrmTicketRequest crmTicketRequest = new RetrieveCrmTicketRequest();
                    crmTicketRequest.OrganizationName = orgUniqueName;
                    crmTicketRequest.PassportTicket = _passportTicket;
                    RetrieveCrmTicketResponse crmTicketResponse = 
                        (RetrieveCrmTicketResponse)discoveryService.Execute(crmTicketRequest);

                    // STEP 7: Create and configure an instance of the CrmService Web service.
                    CrmAuthenticationToken token = new CrmAuthenticationToken();
                    token.AuthenticationType = 1;
                    token.CrmTicket = crmTicketResponse.CrmTicket;
                    token.OrganizationName = crmTicketResponse.OrganizationDetail.OrganizationName;

                    CrmService crmService = new CrmService();
                    crmService.Url = crmTicketResponse.OrganizationDetail.CrmServiceUrl;
                    crmService.CrmAuthenticationTokenValue = token;

                    // Invoke the desired CrmService Web service methods.
                    WhoAmIRequest whoRequest = new WhoAmIRequest();
                    WhoAmIResponse whoResponse = (WhoAmIResponse)crmService.Execute(whoRequest);

                    systemuser user = (systemuser)crmService.Retrieve(
                        EntityName.systemuser.ToString(), whoResponse.UserId, new AllColumns());

                    Console.WriteLine("Login user's name is {0}", user.fullname);
                }
            }
            catch (SoapException ex)
            {
                // Handle the exception thrown from an expired ticket condition.
                if (GetErrorCode(ex.Detail) == EXPIRED_AUTH_TICKET)
                {
                    // Retry CrmService web service call.
                    InvokeServiceMethod(retryCount++);
                }

                // If this was some other SOAP exception, rethrow the exception.
                throw ex;
            }
            catch (Exception ex)
            {
                // Handle the MAX_RETRY exception here.
                // Sample will just rethrow.
                throw ex;
            }
        }

        private static string GetErrorCode(XmlNode errorInfo)
        {
            XmlNode code = errorInfo.SelectSingleNode("//code");

            if (code != null)
                return code.InnerText;
            else
                return "";
        }
    }
}

The CrmDiscoveryService Web service is accessed through the global URL of the Microsoft Dynamics CRM Online server:

https://dev.crm.dynamics.com/MSCRMServices/2007/Passport/CrmDiscoveryService.asmx

If the ticket expires during application execution, a new ticket must be obtained and assigned to the CrmTicket property of the CrmAuthenticationToken instance. If you try to access the CrmService Web methods with an expired ticket, a SOAP exception is thrown. The SoapException.Detail.Innertext property contains the error code value of "8004A101".

Note that, in real-world scenarios, you would never authenticate and then immediately check for an expired ticket as this sample shows. Instead, you would authenticate and make additional Web service method calls. Part of your software design would be to catch Soap exceptions from Microsoft Dynamics CRM Web service calls and check for an expired authentication ticket.

To access the Windows Live authentication service over the Internet and obtain a Windows Live ID ticket, you can use the ticket service library (IDCRL) that is provided in the SDK\Bin folder of the SDK samples. A .NET wrapper is provided in the SDK to access the win32 IDCRL library. The source code for the wrapper can be found in the SDK\Server\Helpers\CS\IdCrlWrapper folder of the SDK samples.

A complete code sample that demonstrates Windows Live authentication can be found in the SDK\Walkthroughs\Authentication\CS|VB\Passport folder of the SDK samples.

See Also

Concepts

Reference

Tasks

Other Resources


© 2010 Microsoft Corporation. All rights reserved.


Show: