Integrating Microsoft Dynamics CRM 2011 Online with Java and other non-.Net Clients

Introduction

While the most common style of .Net development for Microsoft Dynamics CRM Online is using the SOAP endpoint with early or late bound types, there are situations where you need to use the Web Services Description Language (WSDL) endpoint directly. This article is intended to provide some understanding how to leverage this light-weight endpoint that can be used from non-.NET languages. It provides some practical examples in Java that could be transposed to any other popular language.

Microsoft Dynamics CRM Online organizations created since July of 2012 are using the Microsoft Office 365 authentication and billing platform. This was a switch from using Microsoft LiveID since the beginning of Microsoft CRM Online in April of 2008. This article is covering the latest Office 365 Authentication scenario that would fit most of the recent CRM online deployments. An article from the Microsoft Developer Network (referenced at the end of this article) is covering the LiveID scenario.

We’ll start to look at the generation of the Microsoft Dynamics CRM Organization web service stub from its WSDL endpoint and then we’ll see how to authenticate a user via the Office 365 platform’s Secure Token Service (STS) and encode the resulting tokens in a security header securing all operations with the Dynamics CRM Organization service. Finally some of the basic Organization service operations will be covered along with some considerations around performances and potential issues.

Prerequisites for the Java Client

You’ll need of course a subscription or trial to Microsoft Dynamics CRM 2011 Online. If you don’t have a Dynamics CRM Org. available, you can test drive it here: http://www.microsoft.com/en-us/dynamics/crm-test-drive.aspx.

Dynamics CRM Organization Web Service Stub

The Microsoft Dynamics CRM Organization web service stub can be generated with the WSDL2Java command, available right from the bin folder of Apache Axis2:

{Path to Axis2 Lib}\axis2-1.6.2\bin> WSDL2java -uri https://{Your CRM Org domain}.crm.dynamics.com/XRMServices/2011/Organization.svc?wsdl -p {Java package for the generated stub source} -s -o {Path for the generated stub source}

If you prefer to use Apache Ant in order to automate the stub generation, the Ant task would look like this in your build.xml file:

<!—Microsoft Dynamics CRM 2011 Organization Stub generation –>
<target name=“gen-organization-stub”>
    <taskdef  name=“axis2-wsdl2java”
               classname=“org.apache.axis2.tool.ant.AntCodegenTask”
               classpathref=“build.classpath”/>
    <axis2-wsdl2java wsdlfilename=https://{Your CRM Org domain}.crm.dynamics.com/XRMServices/2011/Organization.svc?wsdl packageName={Java package for the generated stub source}output={Path for the generated stub source}syncOnly=”true” /></target>

The URI prefix to the Dynamics CRM 2011 Organization Service should look like https://myCRMOrg.crm.dynamics.com/ if your Organization is hosted in North America, https://myCRMOrg.crm4.dynamics.com/ for EMEA and https://myCRMOrg.crm5.dynamics.com/ for APAC.

An example of Java package could be like “com.mycompany.dynamicscrm.integration” and the path for the generated stub source should be right within your Java project source folder.

Note that with the “s/syncOnly” option of the command, the generated stubs will contain exclusively the synchronous invocation methods.

A detailed documentation of the WSDL2Java command can be found here.

The generated source code for the stub should be a set of 9 Java classes:

Generated Organization Service Stub

OrganizationServiceStub.java is the main stub for the Microsoft Dynamics CRM 2011 Organization Service and the other classes are Java exceptions related to the service’s basic operations.

Authentication via the Microsoft Office 365 Secure Token Service (STS)

Typical STS Authentication request

Here is a typical SOAP/HTTPS request to authenticate a user through the Microsoft Office 365 STS with the associated main headers:

<s:Envelope
xmlns:s=http://www.w3.org/2003/05/soap-envelope&#8221;
        xmlns:a=http://www.w3.org/2005/08/addressing&#8221;
        xmlns:u=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;>
    <s:Header>
        <a:Action
s:mustUnderstand=“1”>http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue</a:Action>
        <a:MessageID>urn:uuid:{Message ID}</a:MessageID>
        <a:ReplyTo><a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address></a:ReplyTo>
        <VsDebuggerCausalityData
xmlns=http://schemas.microsoft.com/vstudio/diagnostics/servicemodelsink&#8221;>
            uIDPo2V68j15KH9PqGf9DWiAfGQAAAAA/Dr1z6qvqUGzr5Yv4aMcdIr9AKDFU7VHn7lpNp0zeXEACQAA</VsDebuggerCausalityData>
        <a:To
s:mustUnderstand=“1”>https://login.microsoftonline.com/RST2.srf</a:To>
        <o:Security
s:mustUnderstand=“1”
                xmlns:o=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221;>
            <u:Timestamp
u:Id=“_0″>
                <u:Created>{Request Timestamp}</u:Created>
                <u:Expires>{Request Expiry Timestamp}</u:Expires>
            </u:Timestamp>
            <o:UsernameToken
u:Id={Token ID}>
                <o:Username>{User Name}</o:Username>
                <o:Password
                Type=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText&#8221;>
                {User Password}</o:Password>
            </o:UsernameToken>
        </o:Security>
    </s:Header>
    <s:Body>
        <t:RequestSecurityToken
xmlns:t=http://schemas.xmlsoap.org/ws/2005/02/trust&#8221;>
            <wsp:AppliesTo
xmlns:wsp=http://schemas.xmlsoap.org/ws/2004/09/policy&#8221;>
                <a:EndpointReference>

                    <a:Address>urn:crmna:dynamics.com</a:Address>

                </a:EndpointReference>

            </wsp:AppliesTo>

                <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType>

        </t:RequestSecurityToken>

    </s:Body>

</s:Envelope>

The Parameters
in red
are the dynamic information to define as variables in every authentication request:

  • {Message ID}: unique request Id, e.g. ‘0d457c4e-8b44-4100-8b7e-085ca6303c7f’,
  • {Request Timestamp} : timestamp of the request (now), e.g. ‘2013-08-17T09:32:27.786Z’,
  • {Request Expiry Timestamp}: timestamp when the request should expire (could be now + 5 minutes), e.g. ‘2013-08-17T09:37:27.786Z’,
  • {Token ID}: unique token Id, e.g. ‘uuid-8c6514f1-8cb5-4c6b-8c0f-e476c7fd7a90-1′,
  • {User Name}: User login, e.g. ‘admin@MyCRMorg.onmicrosoft.com’,
  • {User Password}: User password.

A typical successful authentication answer looks like this:

<?xml
version=“1.0”
encoding=“utf-8″
?>
<S:Envelope
xmlns:S=http://www.w3.org/2003/05/soap-envelope&#8221;

        xmlns:wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221;

        xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

        xmlns:wsa=http://www.w3.org/2005/08/addressing&#8221;>
    <S:Header>
        <wsa:Action
xmlns:S=http://www.w3.org/2003/05/soap-envelope&#8221;

                xmlns:wsa=http://www.w3.org/2005/08/addressing&#8221;

                xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

                wsu:Id=“Action”
S:mustUnderstand=“1”>http://schemas.xmlsoap.org/ws/2005/02/trust/RSTR/Issue</wsa:Action>
        <wsa:To
    xmlns:S=http://www.w3.org/2003/05/soap-envelope&#8221;

                xmlns:wsa=http://www.w3.org/2005/08/addressing&#8221;

                xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

                wsu:Id=“To”
S:mustUnderstand=“1”>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
        <wsse:Security
S:mustUnderstand=“1”>
            <wsu:Timestamp
xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

                     wsu:Id=“TS”>
                <wsu:Created>2013-08-17T09:33:00Z</wsu:Created>
                <wsu:Expires>2013-08-17T09:38:00Z</wsu:Expires>
            </wsu:Timestamp>
        </wsse:Security>
    </S:Header>
    <S:Body>
        <wst:RequestSecurityTokenResponse
    xmlns:S=http://www.w3.org/2003/05/soap-envelope&#8221;

                    xmlns:wst=http://schemas.xmlsoap.org/ws/2005/02/trust&#8221;

                    xmlns:wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221;

                    xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

                    xmlns:saml=“urn:oasis:names:tc:SAML:1.0:assertion”

                    xmlns:wsp=http://schemas.xmlsoap.org/ws/2004/09/policy&#8221;

                    xmlns:psf=http://schemas.microsoft.com/Passport/SoapServices/SOAPFault&#8221;>

            <wst:TokenType>urn:oasis:names:tc:SAML:1.0</wst:TokenType>

            <wsp:AppliesTo
xmlns:wsa=http://www.w3.org/2005/08/addressing&#8221;>

                <wsa:EndpointReference><wsa:Address>urn:crmna:dynamics.com</wsa:Address></wsa:EndpointReference>

            </wsp:AppliesTo>

            <wst:Lifetime>

                <wsu:Created>2013-08-17T09:33:00Z</wsu:Created>

                <wsu:Expires>2013-08-17T17:33:00Z</wsu:Expires>

            </wst:Lifetime>

            <wst:RequestedSecurityToken>

                <EncryptedData
    xmlns=http://www.w3.org/2001/04/xmlenc#&#8221;

                            Id=“Assertion0″

                            Type=http://www.w3.org/2001/04/xmlenc#Element&#8221;>

                    <EncryptionMethod
Algorithm=http://www.w3.org/2001/04/xmlenc#tripledes-cbc&#8221;>

                    </EncryptionMethod>

                    <ds:KeyInfo
xmlns:ds=http://www.w3.org/2000/09/xmldsig#&#8221;>

                        <EncryptedKey>

                            <EncryptionMethod
Algorithm=http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p&#8221;>

                            </EncryptionMethod>

                            <ds:KeyInfo
Id=“keyinfo”>

                                <wsse:SecurityTokenReference>

                                    <wsse:KeyIdentifier
EncodingType=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary&#8221;

                                                 ValueType=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier&#8221;>

                                        D3xjUG3HGaQuKyuGdTWuf6547Lo=

                                    </wsse:KeyIdentifier>

                                </wsse:SecurityTokenReference>

                            </ds:KeyInfo>

                            <CipherData>

                                <CipherValue>{Security Token 0}</CipherValue>

                            </CipherData>

                        </EncryptedKey>

                    </ds:KeyInfo>

                    <CipherData>

                        <CipherValue>{Security Token 1}</CipherValue>

                    </CipherData>

                </EncryptedData>

            </wst:RequestedSecurityToken>

            <wst:RequestedAttachedReference>

                <wsse:SecurityTokenReference>

                    <wsse:KeyIdentifier

                        ValueType=http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID&#8221;>

                        {Key Identifier}

                    </wsse:KeyIdentifier>

                </wsse:SecurityTokenReference>

            </wst:RequestedAttachedReference>

            <wst:RequestedProofToken>

                <wst:BinarySecret>/NbucQb9wbn4h2sZZDpRzwsF8q88SeyP</wst:BinarySecret>

            </wst:RequestedProofToken>

        </wst:RequestSecurityTokenResponse>

    </S:Body>

</S:Envelope>

We can extract from this request the following credentials: the Security Token 0, the Security Token 1 and the Key Identifier.

A typical failed authentication answer, because of invalid credentials, looks like this:

<?xml
version=“1.0”
encoding=“utf-8″
?>

<S:Envelope
xmlns:S=http://www.w3.org/2003/05/soap-envelope&#8221;

        xmlns:wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221;

        xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;

        xmlns:wst=http://schemas.xmlsoap.org/ws/2005/02/trust&#8221;

        xmlns:psf=http://schemas.microsoft.com/Passport/SoapServices/SOAPFault&#8221;>

    <S:Body>

        <S:Fault>

            <S:Code>

                <S:Value>S:Sender</S:Value>

                <S:Subcode>

                    <S:Value>wst:FailedAuthentication</S:Value>

                </S:Subcode>

            </S:Code>

            <S:Reason><S:Text
xml:lang=“en-US”>Authentication Failure</S:Text></S:Reason>

            <S:Detail><psf:error>

                <psf:value>0x80048821</psf:value>

                <psf:internalerror>

                    <psf:code>0x80041012</psf:code>

                    <psf:text>The entered and stored passwords do not match.</psf:text>

                </psf:internalerror>

            </psf:error></S:Detail>

        </S:Fault>

    </S:Body>

</S:Envelope>

Implementation in Java

First create a template with the full authentication SOAP request’s envelope and tokenize the dynamic variables (tokens are defined with %S):

// SOAP envelope template for MSDC Online STS authentication (O365 online platform)
static
public
final String MSDC_ONLINE_AUTH_SOAP_ENVELOPE_TEMPLATE =
“<?xml version=\”1.0\” encoding=\”UTF-8\”?>” +
“<s:Envelope xmlns:s=\”http://www.w3.org/2003/05/soap-envelope\” “ +
“xmlns:a=\”http://www.w3.org/2005/08/addressing\” “ +
“xmlns:u=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\”>” +
” <s:Header>” +
” <a:Action s:mustUnderstand=\”1\”>http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue</a:Action>&#8221; +
” <a:MessageID>urn:uuid:%s</a:MessageID>” +
” <a:ReplyTo><a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address></a:ReplyTo>&#8221; +
” <VsDebuggerCausalityData xmlns=\”http://schemas.microsoft.com/vstudio/diagnostics/servicemodelsink\”>uIDPo2V68j15KH9PqGf9DWiAf
GQAAAAA/Dr1z6qvqUGzr5Yv4aMcdIr9AKDFU7VHn7lpNp0zeXEACQAA</VsDebuggerCausalityData>” +
” <a:To s:mustUnderstand=\”1\”>https://login.microsoftonline.com/RST2.srf</a:To>&#8221; +
” <o:Security s:mustUnderstand=\”1\” xmlns:o=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\”>” +
” <u:Timestamp u:Id=\”_0\”>” +
” <u:Created>%s</u:Created>” +
” <u:Expires>%s</u:Expires>” +
” </u:Timestamp>” +
” <o:UsernameToken u:Id=\”%s\”>” +
” <o:Username>%s</o:Username>” +
” <o:Password Type=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText\”>
%s</o:Password>” +
” </o:UsernameToken>” +
” </o:Security>” +
” </s:Header>” +
” <s:Body>” +
” <t:RequestSecurityToken xmlns:t=\”http://schemas.xmlsoap.org/ws/2005/02/trust\”>” +
” <wsp:AppliesTo xmlns:wsp=\”http://schemas.xmlsoap.org/ws/2004/09/policy\”>” +

” <a:EndpointReference>” +

” <a:Address>urn:crmna:dynamics.com</a:Address>” +

” </a:EndpointReference>” +

” </wsp:AppliesTo>” +

” <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType>&#8221; +

” </t:RequestSecurityToken>” +

” </s:Body>” +

“</s:Envelope>”;

Generate the dynamic token values and prepare the SOAP request in order to authenticate a user through the Microsoft Online STS:

// Prepare input parameter for CRM Authentication Request
// > Random Message Id
String paramMessageId = UUID.randomUUID().toString();
// > Request Timestamp and +5 minutes validity
TimeZone gmtTZ = TimeZone.getTimeZone(“GMT”);
SimpleDateFormat formatter = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss”);
formatter.setTimeZone(gmtTZ);
Calendar calendar = Calendar.getInstance(gmtTZ);
Date timestampRequest = calendar.getTime();
calendar.add(Calendar.MINUTE, 5);
Date timestampExpiryRequest = calendar.getTime();
String paramTimestampRequest = formatter.format(timestampRequest);
String paramTimestampExpiryRequest = formatter.format(timestampExpiryRequest);
// > Random Token Id
String paramTokenId = “uuid-“ + UUID.randomUUID().toString() + “-1″;
// Prepare CRM Online authentication SOAP request
String onlineCRMAuthSOAPEnvelope = String.format(
    MSDC_ONLINE_AUTH_SOAP_ENVELOPE_TEMPLATE,
    paramMessageId,
    paramTimestampRequest,
    paramTimestampExpiryRequest,
    paramTokenId,
    userName,
    userPassword);

Now it is time to send the authentication request to the Microsoft Online STS, via SOAP/HTTPS …

// Send CRM Online authentication SOAP request to Microsoft online STS
String onlineCRMAuthResponseXML = postSOAPRequest(
    “https://login.microsoftonline.com/RST2.srf“,
    onlineCRMAuthSOAPEnvelope);

… For that, we can leverage the Apache HTTP Components:

public
static String postSOAPRequest(URI serviceUri, String soapEnvelope) throws ParseException, IOException {
    HttpResponse response = null;
    HttpParams params = new BasicHttpParams();
    params.setParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 180000); //time out in ms
    HttpClient client = new DefaultHttpClient(params);
HttpPost post = new HttpPost(serviceUri);
StringEntity entity = new StringEntity(soapEnvelope);
post.setHeader(“Content-Type”, “application/soap+xml; charset=UTF-8″);
post.setEntity(entity);
response = client.execute(post);

return EntityUtils.toString(response.getEntity());
}

Finally, parse the SOAP response from the STS and gather 3 credentials: securityToken0, securityToken1
and keyIdentifier.

If the credentials cannot be found, then we assume we are facing a failed authentication answer. In that case, the reason and the detail of the error can be parsed instead:

// Parse the CRM Online authentication SOAP response from STS
// Create a Java DOM XML Parser
DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = builderFactory.newDocumentBuilder();
// Parse XML with Java DOM XML Parser
Document xmlDocument = builder.parse(new ByteArrayInputStream(onlineCRMAuthResponseXML.getBytes()));
            
// Retrieve security tokens and key identifier from security token response.
XPath xpath = XPathFactory.newInstance().newXPath();
String securityToken0 = readStringValFromXmlDocument(xmlDocument, “//*[local-name()=’CipherValue’]”,xpath);

// If first token is blank, search eventual authentication failure message
if((securityToken0==null)||(securityToken0.isEmpty())){
    String errorReason = readStringValFromXmlDocument(xmlDocument, “//*[local-name()=’Reason’]”,xpath);
    String errorDetail = readStringValFromXmlDocument(xmlDocument, “//*[local-name()=’Detail’]”,
        xpath).substring(20);
            
    if((errorReason!=null)&&(errorReason.equalsIgnoreCase(“Authentication Failure”))){
        logger.debug(“Failed authentication for User ‘” + userName + “‘. Reason is ‘” + errorReason +
                            “‘ and Detail is “ + errorDetail);
        throw
new MSDCAuthenticationException(errorDetail); // Exception to craft according to your needs
    } else {
        logger.debug(“Failed authentication for User ‘” + userName + “‘ but cannot parse the reasons”);
        throw
new MSDCAuthenticationException (“Failed authentication for unexpected reasons);
    }
}
String securityToken1 = readStringValFromXmlDocument(xmlDocument, “(//*[local-name()=’CipherValue’])[2]”,xpath);
String keyIdentifier = readStringValFromXmlDocument(xmlDocument, “//*[local-name()=’KeyIdentifier’]”, xpath);

Implementation for the method readStringValFromXmlDocument: 

public static String readStringValFromXmlDocument(Document xmlDocument, String xpathQueryExpression, XPath xpathInstance) throws XPathExpressionException {return xpathInstance.compile(xpathQueryExpression).evaluate(xmlDocument);
}

Calling Dynamics CRM Organization Service Invocation Methods in Java

Instantiation of the Organization Service Stub

In order to instantiate the Organization Service Stub from the Java classes generated from the WSDL, we must first configure Axis2 by creating a configuration context from the ‘axis2.xml’ file that we placed at the root of the project source code. This file is a copy of the standard ‘axis2.xml’ file that can be found in the ‘conf’ directory of the Axis2 Java library.

We need to also pass, along with the configuration context, the URL of the Dynamics CRM 2011 Online Organization.

// Create OrganizationServiceStub
String fileSeperator = System.getProperty(“file.separator”);
String userDir = System.getProperty(“user.dir”);
String axis2ConfigFilePath = userDir + fileSeperator + “src” + fileSeperator + “axis2.xml”;
                
ConfigurationContext ctx = ConfigurationContextFactory.createConfigurationContextFromFileSystem(userDir, axis2ConfigFilePath);
organizationServiceStub = new OrganizationServiceStub(ctx, https://myCRMOrg.crm.dynamics.com);
                
// Get service client implementation used by this stub.
serviceClient = organizationServiceStub._getServiceClient();

We keep most of the default parameters in the ‘axis2.xml’ file except a custom inflow predefined Phase called ‘MustUnderstandChecker’ that must be declared in this file:

. . .
<!– ================================================= –>
<!– Phases –>
<!– ================================================= –>
<phaseOrder
type=“InFlow”>
. . .            
    <phase
name=“RMPhase”/>
    <!– System predefined phases –>
    <!– After Postdispatch phase module author or service author can add any phase he want –>
     <phase
name=“OperationInPhase”>
    <handler
name=MustUnderstandChecker
    class=
com.mycompany.dynamicscrm.integration.Axis2MustUnderstandChecker>
        <order
phase=“OperationInPhase”/>
    </handler>
    </phase>
    . . .
</phaseOrder>
. . .

Here is an implementation of the Axis2MustUnderstandChecker class that tells Axis2 client to process the security SOAP header block from the message context header:

/***
* Handler for SOAP header.
*
*/
public
final
class Axis2MustUnderstandChecker extends AbstractHandler {

public Axis2MustUnderstandChecker() {
}

/* (non-Javadoc)
* Process the Security SOAP header block from the message context header.
* @see org.apache.axis2.engine.Handler#invoke(org.apache.axis2.context.MessageContext)
*/

public InvocationResponse invoke(MessageContext msgContext)

throws AxisFault {
SOAPHeader header = msgContext.getEnvelope().getHeader();

if (header != null) {
Iterator<?> blocks = header.examineAllHeaderBlocks();

while (blocks.hasNext()) {
SOAPHeaderBlock block = (SOAPHeaderBlock) blocks.next();

if(block != null){     
    if (block.getLocalName().equals(“Security”)) {
        block.setProcessed();
    }
}
}
}

return InvocationResponse.CONTINUE;
}
}

SOAP Requests options and Security SOAP header block

After the instantiation of the Organization Service Stub, some options must be set and a fresh Security SOAP header block must be defined:

try {
    Options scOptions = serviceClient.getOptions();
    scOptions.setMessageId(“urn:uuid:” + UUID.randomUUID().toString());
    EndpointReference endPoint = new EndpointReference(http://www.w3.org/2005/08/addressing/anonymous&#8221;);
    scOptions.setReplyTo(endPoint);
    serviceClient.setOptions(scOptions);
            
    // Add fresh Security SOAP Header block
    serviceClient.addHeader(generateFreshSecuritySoapHeaderBlock(securityHeader));
    serviceClient.engageModule(“addressing”);
            
} catch (AxisFault af) {
            throw
new MSDCIntegrationException(“Unexpected web service error”, af);
}

Here is the detail of the method ‘generateFreshSecuritySoapHeaderBlock’
that generate a brand new security SOAP header block including some fresh timestamps with a validity period (set arbitrarily in our case to 5 minutes) and a security header embedding the credentials from the Microsoft Online STS authentication:

private SOAPHeaderBlock generateFreshSecuritySoapHeaderBlock (String securityHeaderStr) throws XMLStreamException {
        
    SOAPHeaderBlock securitySoapHeaderBlock = null;
    OMFactory omFactory = OMAbstractFactory.getOMFactory();
    OMNamespace securitySecextNS = omFactory.createOMNamespace(http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd&#8221;, “o”);
    OMNamespace securityUtilityNS = omFactory.createOMNamespace(http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd&#8221;, “u”);
    
    // Create fresh Time stamp element for the SOAP header block
    TimeZone gmtTZ = TimeZone.getTimeZone(“GMT”);
    SimpleDateFormat formatter = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss”);
    formatter.setTimeZone(gmtTZ);
    Calendar calendar = Calendar.getInstance(gmtTZ);
    Date timestampRequest = calendar.getTime();
    calendar.add(Calendar.MINUTE, 5);
    Date timestampExpiryRequest = calendar.getTime();
    String timestampRequestStr = formatter.format(timestampRequest);
    String timestampExpiryRequestStr = formatter.format(timestampExpiryRequest);
    
    OMElement timeStampElement = omFactory.createOMElement(“Timestamp”, securityUtilityNS);
    timeStampElement.addAttribute(“Id”, “_0″, securityUtilityNS);
    OMElement createdElement = omFactory.createOMElement(“Created”, securityUtilityNS);
    OMText createdTime = omFactory.createOMText(timestampRequestStr + “Z”);
    createdElement.addChild(createdTime);
    OMElement expiresElement = omFactory.createOMElement(“Expires”, securityUtilityNS);
    OMText expiresTime = omFactory.createOMText(timestampExpiryRequestStr + “Z”);
    expiresElement.addChild(expiresTime);
    timeStampElement.addChild(createdElement);
    timeStampElement.addChild(expiresElement);

    // Create the Security SOAP header block and add, as a child, Time stamp element

    securitySoapHeaderBlock = OMAbstractFactory.getSOAP12Factory().createSOAPHeaderBlock(“Security”, securitySecextNS);

    securitySoapHeaderBlock.setMustUnderstand(true);

    securitySoapHeaderBlock.addChild(timeStampElement);

    securitySoapHeaderBlock.addChild(AXIOMUtil.stringToOM(omFactory, securityHeaderStr));

    

    return securitySoapHeaderBlock;

}

The method ‘generateFreshSecuritySoapHeaderBlock’ takes the Security Header string as an input parameter and it can be built with the following template:

// Security header template
static
public
final String MSDC_SECURITY_HEADER_TEMPLATE =
“<EncryptedData xmlns=\”http://www.w3.org/2001/04/xmlenc#\” Id=\”Assertion0\” Type=\”http://www.w3.org/2001/04/xmlenc#Element\”>” +
”    <EncryptionMethod Algorithm=\”http://www.w3.org/2001/04/xmlenc#tripledes-cbc\”/>” +
”    <ds:KeyInfo xmlns:ds=\”http://www.w3.org/2000/09/xmldsig#\”>” +
”        <EncryptedKey>” +
”            <EncryptionMethod Algorithm=\”http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p\”/>” +
”            <ds:KeyInfo Id=\”keyinfo\”>” +
”                <wsse:SecurityTokenReference xmlns:wsse=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\”>” +
”                    <wsse:KeyIdentifier EncodingType=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary\” “ +
”                        ValueType=\”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier\”>%s</wsse:KeyIdentifier>” +
”                </wsse:SecurityTokenReference>” +
”            </ds:KeyInfo>” +
”            <CipherData>” +
”                <CipherValue>%s</CipherValue>” +
”            </CipherData>” +
”        </EncryptedKey>” +
”    </ds:KeyInfo>” +
”    <CipherData>” +
”        <CipherValue>%s</CipherValue>” +
”    </CipherData>” +
“</EncryptedData>”;

Generate the security header string with the following Java code, replacing the 3 tokens in the template by the credentials obtained from the Microsoft Online STS authentication:

// Generate security header
securityHeader = String.format(
    MSDC_SECURITY_HEADER_TEMPLATE,
    keyIdentifier,
    securityToken0,
    securityToken1);

Stub Invocation Methods

Here is an example of a high level ‘Create’ method that create an object in Dynamics CRM 2011 Online with the following parameters:

  • entityLogicalName: the logical name of the entity to create, e.g. ‘account’,
  • attributesHash: an HashMap of attributes (pairs of attribute keys and values), e.g. {“name”, “Test Account”},{“address1_city”, “Paris”}, etc.,
  • organizationService: the Dynamics CRM Organization Service stub instantiated and augmented with the options and the fresh Security SOAP header block.
public String executeCreate(String entityLogicalName, HashMap<String,String> attributesHash, OrganizationServiceStub organizationService) throws MSDCIntegrationException {
        
    // Transfer attributes from HashMap to Stub attribute collection
    OrganizationServiceStub.AttributeCollection attributeCollection = new OrganizationServiceStub.AttributeCollection();
    Iterator<String> it = attributesHash.keySet().iterator();
    while(it.hasNext()){
        String key = it.next();
        OrganizationServiceStub.KeyValuePairOfstringanyType KeyValuePair =
            new OrganizationServiceStub.KeyValuePairOfstringanyType();
         KeyValuePair.setKey(key);
     KeyValuePair.setValue(attributesHash.get(key));
     attributeCollection.addKeyValuePairOfstringanyType(KeyValuePair);
    }
    // Create Entity with attributes
    OrganizationServiceStub.Entity entity = new OrganizationServiceStub.Entity();
entity.setLogicalName(entityLogicalName);
entity.setAttributes(attributeCollection);
OrganizationServiceStub.Create createEntity = new OrganizationServiceStub.Create();
createEntity.setEntity(entity);

// Send Create command to Organization web service
String resultGuid = null;

try {
    OrganizationServiceStub.CreateResponse createResponse;
        createResponse = organizationService.create(createEntity);
        OrganizationServiceStub.Guid createResultGuid = createResponse.getCreateResult();
        resultGuid = createResultGuid.getGuid();    
    } catch (RemoteException
| IOrganizationService_Create_OrganizationServiceFaultFault_FaultMessage e) {
        throw
new MSDCIntegrationException(“Unexpected web service error”,
e);

    }

    logger.debug(“Entity ‘” + entityLogicalName + “‘ created successfully with GUID = “ + resultGuid);


return resultGuid;

}

Here are some of the other public methods you can invoke on the Organization Service stub:

  • Associate: Creates a link between records.
  • Delete: Deletes a record.
  • Disassociate: Deletes a link between records.
  • Execute: Executes a message in the form of a request, and returns a response.
  • Retrieve: Retrieves a record.
  • RetrieveMultiple: Retrieves a collection of records.
  • Update: Updates an existing record.

Performance considerations

Instantiating the Organization Service stub can takes up to 75% of the time of a single transaction, this is why this operation should be minimized at any cost.

It is recommend to keep the same stub instance with one security header for a few consecutive operations within a single stateless transaction. The security SOAP header block has got a timestamp with a validity period and this period should not expire.

If the application is stateful, the stub can be cached. Once instantiated, the security SOAP header block can be regenerated for each further usages. The cost of this operation is minimal.

Before to rebuild a security SOAP header block, the headers of the stub’s service client must be cleared with the command ‘removeHeaders()':

// Recycling organizationServiceStub
serviceClient = organizationServiceStub._getServiceClient();
// Remove existing headers in order to produce a fresh one
serviceClient.removeHeaders();

Troubleshooting

  • Always make sure that the account used to authenticate on the Dynamics CRM server is valid and that it has the required privileges to execute the desired operations on the Organization service.
  • Undeclared namespace prefix “wsx” Exception at Java runtime when instantiating OrganizationServiceStub:
    • Exception detail: org.apache.neethi.builders.converters.ConverterException: com.ctc.wstx.exc.WstxParsingException: Undeclared namespace prefix “wsx”
    • Probable cause: the generated stub is declaring the “wsx” domain for some tags that are already embedded within some tags from the same domain and the domain is locally declared and not with a global prefix.
    • Proposed solution: edit the generated Organization Service stub “OrganizationServiceStub.java”, search and replace:
      • wsx:MetadataReference by MetadataReference
      • wsx:MetadataSection by MetadataSection
  • The code samples exposed in this article have been tested only with Dynamics CRM 2011 Online (version 5.0.9690.5010, DB 5.0.9690.3417) and not yet with Dynamics CRM 2013. Some changes will need to be implemented once this new version is officially released.

Conclusion

This article has demonstrated a reliable and quite easy to implement way to integrate Dynamics CRM 2011 Online with Java. The different network frames and algorithms have been detailed so they can be adapted with other languages.

The codes samples of this article have been tested in development but in no mean on a production environment. So prior to implement it in production, adequate testing should be considered and this project will be at your own risks.

The next steps would be to push further this approach to Dynamics CRM On Premise:

  • Internet Facing Deployment with ADFS 2.0
  • Windows authentication

References

Source Code on GitHub

You’ll find a full implementation of the approach explained in this article on the following GitHub repository: https://github.com/pdellecase/CRMJavaConnect

MSDN CoE Blog

This article is also published on the Microsoft Dynamics Center of Excellence Blog : http://blogs.msdn.com/b/dynamics-coe/archive/2013/09/21/integrating-microsoft-dynamics-crm-2011-online-with-java-and-other-non-net-clients.aspx

Microsoft Developer Network article: Connect Using Java for Microsoft Dynamics CRM Online

This great article walks you through a basic sample code to integrate Dynamics CRM 2011 Online with Java. The authentication is through LiveID and would not work anymore for recently provisioned Dynamics CRM 2011 Online Organizations.

At the beginning, I was trying hard to generate the Microsoft Dynamics CRM Organization Service stubs with the Java API for XML Web Services (JAX-WS), without any success. This article put me on the right track with the Apache Axis2 library that can parse the Organization Service WSDL without any fatal errors.

Link to the MDN article: http://msdn.microsoft.com/en-us/library/jj602979.aspx

Microsoft Developer Network article: Download the Endpoints Using the Dynamics CRM Developer Resources Page

This article explains how to download the WSDL from the developer resources pages in the Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online Web application. It provides also some details about the Discovery Service and the Organization Service WSDLs.

Link to the MDN article: http://msdn.microsoft.com/en-us/library/gg309401.aspx

Microsoft Developer Network article: IOrganizationService Interface > IOrganizationService Members

This article list the public methods members exposed by the IorganizationService interface, with all their parameters, and is a good starting point to find practical samples of code.

Link to the MDN article: http://msdn.microsoft.com/en-us/library/microsoft.xrm.sdk.iorganizationservice_members.aspx

The Microsoft Dynamics CRM 2011 Software Development Kit (SDK)

The official SDK for Dynamics CRM provided by Microsoft contains many useful .Net samples to get started. I have used some of these samples to monitor, with a tool like Fiddler, the HTTPS traffic between my PC and Microsoft Dynamics CRM in order to gather the authentication request sent to the Office 365 Secure Token Service and the security header from the SOAP requests.

Link to the Microsoft Dynamics CRM 2011 SDK Documentation: http://msdn.microsoft.com/en-us/library/hh547453.aspx

Link to the Microsoft Dynamics CRM 2011 SDK: http://www.microsoft.com/en-us/download/details.aspx?id=24004

About these ads
Tagged with: , , , , , , , , , , ,
Posted in CRM, Integration, Java, Microsoft Dynamics CRM 2011, Technical Architecture
10 comments on “Integrating Microsoft Dynamics CRM 2011 Online with Java and other non-.Net Clients
  1. Daniel Cai says:

    Nice work, thanks for sharing, look forward to the full release on github.

  2. Doug Hitchcock says:

    Where can I find the source for MSDCSoapHelper?

  3. pdellecase says:

    Hello, yes I didn’t have time yet to post the code in GitHub. I am just starting with both WordPress and GitHub and I want to do things right. I’ll try to do that this weekend alright ?
    I removed most of the dependencies in order to simplify things but it is true that one method is still depending on the class MSDCSoapHelper, I will also correct that, but you’ll get everything in the source code much better structured.

  4. Doug Hitchcock says:

    I am trying to do this same thing but with an ADFS server. I ran the Authentication solution from the CRM SDK and sniffed all the traffic it did, and have been trying to reproduce it in Java.

    I’ve posted username & pass to our ADFS server and gotten a token.

    I take that token and posted it to https://login.microsoftonline.com/RST2.srf, which gives me back two cipher’s and a Key Identifier.

    I then am trying to Post those cipers to https://dynamicscrmna.accesscontrol.windows.net/v2/wstrust/13/issuedtoken-asymmetric, but I can’t figure out how to sign the XML, to re-create this piece:

    QyGPAxe2XVNMMBwJggMMLhiBALU=

    d9RuRpWpWdUB7nJJ2Bv+eNRDJjY=

    uuid-2a5b3c63-18cb-40a8-9a18-9252a05fe50e

    You mentioned ADFS 2.0 should be easy. Am I making this too difficult, can you give any hints of the easy way to do the ADFS authentication? Thanks!

  5. pdellecase says:

    Hello, the code has been checked-in into GitHub. Hope it helps.

    Dough, I am not sure to understand your scenario. You mentioned ADFS 2.0, so I guess you are OnPremise right ? so why do you post to https://login.microsoftonline.com/RST2.srf ? Everything should stay in your local environment.
    Once you got the 2 tokens and 1 key identifier, you should mimic what you got when sniffing the HTTP signals for a specific command on the API (CRUD operation).
    I actually sniffed the http traffic too, with Fiddler, in order to create this article, and a lot of the HTTP requests are to fetch the dependencies ; you have to make sure you are reproducing the right ones.
    I guess it should be pretty similar to the Online Case, but I cannot verify since I do not own currently an OnPremise CRM deployment.

  6. Doug Hitchcock says:

    I post to RST2.srf because that’s what I sniffed the sample program doing, and I’m just trying to replicate all of its steps. I can’t figure out how though, the important pieces I want to see I can’t step into when debugging:

    CrmServiceHelpers:803
    AuthenticationCredentials tokenCredentials =
    serviceManagement.Authenticate(
    authCredentials);

    This is using the solution from the SDK in samplecode\cs\generalprogramming\authentication

    I’m not familiar with OnPremise, I’m just a java guy on the outside, though I can ask the insiders if that’s important information. What I have is java application that makes calls to CRM web service. It obtains the Key Identifier and ciphers from the sample code walkthroughs/java2crm in the SDK. Then we stick those values into the headers of our web service calls. Now our client wants us to authenticate using their ADFS server instead.

    If it helps any, if I run your code in git, I get error code 0x80047860: Direct login to WLID is not allowed for this federated namespace

    Thanks!

    • Doug Hitchcock says:

      It’s ok, forget what I’m doing, it’s probably way off. I am still just hanging on the hope from when you said:

      Internet Facing Deployment with ADFS 2.0: this adaptation should be simple given the similarity of the Secure Token Service.

      Can you please finish that thought and clue me in to what needs to change in your sample to work with an ADFS server?

      Thank you!

  7. Doug Hitchcock says:

    Hi,

    I have seen the link to signing-soap-message-request-via-adfs, I had just hoped it was easier than that. I actually did try to implement the walkthrough at that link, but I didn’t know where I could find both binary secrets. The adfs server returns one binary secret, but I didn’t know which one it was and where the other one was. Plus I wasn’t sure how to translate that C# CalculatePSHA1 method into Java.

    We’ve ended up having the client set up a .net web service based on the authentication demo and just return to us our token. Anti-climatic for your blog spot, but we had been stuck on it far too long and were just happy to be able to get it working. If you or anyone else has any other breakthroughs though we may revisit it.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: