SOAP API

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:

http://localhost:8095/crowd/services/SecurityServer?wsdl

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

http://docs.atlassian.com/crowd/current/com/atlassian/crowd/integration/service/soap/server/SecurityServer.html

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>

findPrincipalByToken - Finding a Principal by their Authenticated Token

Now that the principal is authenticated, we may want to find additional details about the principal. With the authenticated principal token, the application can now look up a user by a token or their name. The example below shows looking up a principal by their authenticated 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>
		<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 for the principal 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>
        <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>

Child pages

authenticateApplication - Authenticating an Application Client

authenticatePrincipal - Authenticating a Principal

findPrincipalByToken - Finding a Principal by their Authenticated Token

関連トピック