Last updated Mar 21, 2022

SOAP API

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

SOAP API is no longer available

SOAP API has been removed in Crowd 5.0. For information on how to migrate to REST API, see Crowd SOAP to REST migration guide.

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

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.

1
2
<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>
                    <encryptedCredential>false</encryptedCredential>
                </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:

1
2
<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.

1
2
<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>
                    <encryptedCredential>false</encryptedCredential>
                </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:

1
2
<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:

1
2
<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:

1
2
<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:

1
2
<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.

Crowd documentation

Rate this page: