This page last changed on Feb 24, 2009 by dyu.

This page provides sample code for creating a Crowd Client using the SOAP API.

The Crowd API has been tested with: Axis 1/2, Microsoft .NET and XFire.

The SOAP WSDL is available on the following URL for the Crowd Standalone version (after you have downloaded and installed Crowd Standalone):

The Java Remote Interface that is used to generate the SOAP service is available here:

This JavaDoc file details inputs and outputs for the available Crowd security server SOAP server. You will see that all methods require an AuthenticatedToken. A valid token can be obtained by calling the authenticateApplication service method.

Like a user token, the application client token is valid only for the same period of time a user token would be. If you receive a SOAP fault for an invalid application client you will need to re-authenticate your application client and re-invoke the SOAP service.

Crowd ships with out of the box Java Integration Libraries that map one-to-one to these web services.

authenticateApplication - Authenticating an Application Client

Here is the server request which passes in the server name and a password credential.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Body>
		<authenticateApplication xmlns="urn:SecurityServer">
			<in0>
				<credential xmlns="http://authentication.integration.crowd.atlassian.com">
					<credential>password</credential>
				</credential>

				<name xmlns="http://authentication.integration.crowd.atlassian.com">jira</name>

				<validationFactors xmlns="http://authentication.integration.crowd.atlassian.com" xsi:nil="true" />
			</in0>
		</authenticateApplication>
	</soap:Body>
</soap:Envelope>

The server will respond with an application token:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Body>
		<authenticateApplicationResponse xmlns="urn:SecurityServer">
			<out>
				<name xmlns="http://authentication.integration.crowd.atlassian.com">jira</name>
				<token xmlns="http://authentication.integration.crowd.atlassian.com">9vN5haaWY+xGBs3XitgAIg==</token>
			</out>
		</authenticateApplicationResponse>
	</soap:Body>
</soap:Envelope>

authenticatePrincipal - Authenticating a Principal

In this message the principal is authenticated using the previously obtained application token.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Body>
		<authenticatePrincipal xmlns="urn:SecurityServer">
			<in0>
				<name xmlns="http://authentication.integration.crowd.atlassian.com">jive</name>
				<token xmlns="http://authentication.integration.crowd.atlassian.com">9vN5haaWY+xGBs3XitgAIg==</token>
			</in0>
			<in1>
				<application xmlns="http://authentication.integration.crowd.atlassian.com">jive</application>
				<credential xmlns="http://authentication.integration.crowd.atlassian.com">
					<credential>password</credential>
				</credential>
				<name xmlns="http://authentication.integration.crowd.atlassian.com">jstepka</name>
				<validationFactors xmlns="http://authentication.integration.crowd.atlassian.com" />
			</in1>
		</authenticatePrincipal>
	</soap:Body>
</soap:Envelope>

The server then responds with the token for the now authenticated user:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Body>
		<authenticatePrincipalResponse xmlns="urn:SecurityServer">
			<out>o7MSozJJbKQttOLvC4hN2w==</out>
		</authenticatePrincipalResponse>
	</soap:Body>
</soap:Envelope>

An invalid authentication attempt will look like the following:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Fault: com.atlassian.crowd.integration.exception.InvalidAuthenticationException</faultstring>
            <detail>
                <InvalidAuthenticationException xmlns="urn:SecurityServer"/>
            </detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

findPrincipalByName - Finding a Principal by their Name

Now that the principal is authenticated, we may want to find additional details about the principal. The application can now look up a user by a token or their name. The example below shows looking up a principal by their name:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Body>
		<findPrincipalByName xmlns="urn:SecurityServer">
			<in0>
				<name xmlns="http://authentication.integration.crowd.atlassian.com">jive</name>
				<token xmlns="http://authentication.integration.crowd.atlassian.com">9vN5haaWY+xGBs3XitgAIg==</token>
			</in0>
			<in1>jstepka</in1>
		</findPrincipalByName>
	</soap:Body>
</soap:Envelope>

The server lookup response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <findPrincipalByNameResponse xmlns="urn:SecurityServer">
            <out>
                <ID xmlns="http://soap.integration.crowd.atlassian.com">-1</ID>
                <active xmlns="http://soap.integration.crowd.atlassian.com">true</active>
                <attributes xmlns="http://soap.integration.crowd.atlassian.com">
                    <SOAPAttribute>
                        <name>sn</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">Stepka</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>invalidPasswordAttempts</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">0</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>requiresPasswordChange</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">false</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>mail</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">justen.stepka@atlassian.com</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>lastAuthenticated</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">1169440408520</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>givenName</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">Justen</ns1:string>
                        </values>
                    </SOAPAttribute>
                    <SOAPAttribute>
                        <name>passwordLastChanged</name>
                        <values>
                            <ns1:string xmlns:ns1="urn:SecurityServer">1168995491407</ns1:string>
                        </values>
                    </SOAPAttribute>
                </attributes>
                <conception xmlns="http://soap.integration.crowd.atlassian.com">2007-01-17T11:58:11+11:00</conception>
                <description xmlns="http://soap.integration.crowd.atlassian.com" xsi:nil="true"/>
                <directoryID xmlns="http://soap.integration.crowd.atlassian.com">1</directoryID>
                <lastModified xmlns="http://soap.integration.crowd.atlassian.com">2007-01-17T18:38:51+11:00
                </lastModified>
                <name xmlns="http://soap.integration.crowd.atlassian.com">jstepka</name>
            </out>
        </findPrincipalByNameResponse>
    </soap:Body>
</soap:Envelope>


Please refer to the JavaDoc for the full list of exposed SOAP methods.

Related Topics

Crowd Documentation  

Document generated by Confluence on Jul 30, 2009 01:30