SOAP API

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

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

• 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/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.

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.

Related Topics

• Application Integration Overview
  • Sample Application ('demo')
• Crowd 2.1 Java Client Migration Guide
  • Crowd 2.1 REST Java Client Migration Guide
  • Crowd 2.1 SOAP Java Client Migration Guide
• Java Integration Libraries
  • Compiling the Crowd Source
  • Creating a Crowd Client using Crowd Integration Libraries
  • Maven 2 Integration
  • Using the Search API
• SOAP API
  • Axis 1.x Client Stub Generation
  • Microsoft .NET Client

Crowd documentation