Java Integration Libraries

This page provides sample code for creating a Crowd Client using the supplied Java integration libraries.

SecurityServerClient

The SecurityServerClient is useful for common create, update and delete operations for principals, groups and roles. To accomplish this, the SecurityServerClient maps 1-to-1 with the SOAP API of the Crowd server. The class reads in the crowd.properties configuration file from your application's class path, setting client specific details such as the Crowd server URL and SSO integration details. When the client is loaded into memory, it will then authenticate the the client application with the Crowd security server for future SOAP requests.

A full list of the available methods for the SecurityServerClient is available here:

• http://docs.atlassian.com/crowd/current/com/atlassian/crowd/integration/service/soap/client/SecurityServerClient.html

HttpAuthenticator

The HttpAuthenticator simplifies the authentication of HTTP based clients. When an authentication or invalidation is performed, the HttpAuthenticator manages the setting and resetting of integration variables for the principal's HTTP session. If the application has little need beyond authentication and validation, the HttpAuthenticator is a simple and very straightforward integration piece. Shown below is a code example of authenticating and logging off a principal:

例 1:

HttpAuthenticatorFactory.getHttpAuthenticator().authenticate(request, response, username, password);

例 2:

HttpAuthenticatorFactory.getHttpAuthenticator().logoff(request, response);

If there were any issues with the authentication or logoff calls, an Exception will be thrown to the application.

The HttpAuthenticator manages the following:

• Authenticating an HTTP request, and setting the session with the correct attributes for other integration points of the framework.
• Invalidating an HTTP request includes removing session related attributes.
• Obtaining a principal's authenticated token from a session or browser cookie.
• Validating an existing HTTP authentication for single sign-on. If another application in the same domain has already authenticated the principal, the HttpAuthenticator will attempt to validate the existing authentication.
• Building a standard AuthenticationContext for a principal. This can be used to assure the authentication is consistent across all applications when setting validation factors of the application client.

Note both the HttpAuthenticatorFactory and SecurityServerClientFactory manage singleton instances of the HttpAuthenticator and SecurityServerClient implementations respectively. You should never need to instantiate the HttpAuthenticator or SecurityServerClient manually.

VerifyTokenFilter

The VerifyTokenFilter is an HTTP servlet filter that protects secured resources by verifying the session or cookie token is active and the principal has access to the requesting application. The token filter works in conjunction with the HttpAuthenticator, validating and setting various session and cookie attributes. Should the principal's token become expired or invalid due to security restrictions, the principal will be redirected to the URL provided by the crowd.properties.

Using the token filter is very straight forward, simply edit your web.xml deployment descriptor to reflect the filter and desired resource mapping:

<filter>
    <filter-name>VerifyTokenFilter</filter-name>
    <filter-class>com.atlassian.crowd.integration.http.VerifyTokenFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>VerifyTokenFilter</filter-name>
    <url-pattern>/secure/*</url-pattern>
</filter-mapping>

In this example, the verify token filter will prevent any pages on the /secure/ path from being accessed unless a valid token is found.

Should the token expire or be found invalid, the original URL will be stored in the principal's session at a String with the key of VerifyTokenFilter.ORIGINAL_URL. This is useful because, when the principal later authenticates, the original URL and parameters can then be used as a redirect bringing the principal back to their original POST. An example of how this can be accomplished at login is shown below:

HttpAuthenticatorFactory.getHttpAuthenticatory().authenticate(request, response, username, password);

// Check if principal was requesting a page that was prevented, if so, redirect.
String requestingPage = (String) getSession().getAttribute(VerifyTokenFilter.ORIGINAL_URL);

if (requestingPage != null) {
    // redirect the principal to the requesting page
    response().sendRedirect(requestingPage);

} else {
    // return the to the login page
    return SUCCESS;
}

Using dependency injection?

If you are using a dependency injection container which manages singleton instances, rather than using the SecurityServerClientFactory and HttpAuthenticatorFactory to manage singletons, you can wire up the objects themselves as shown in the following diagram:

If you are using Spring for dependency injection, a convenient applicationContext-CrowdClient.xml has been provided in the crowd-integration-client.jar. This Spring configuration file wires up the HttpAuthenticator and SecurityServerClient factory as beans named httpAuthenticator and securityServerClient respectively.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans-2.0.dtd">

<beans>

    <bean id="propertyUtils" class="com.atlassian.crowd.util.PropertyUtils"/>

    <bean id="clientProperties" class="com.atlassian.crowd.integration.service.soap.client.ClientProperties">
        <constructor-arg ref="propertyUtils"/>
    </bean>

    <bean id="securityServerClient" class="com.atlassian.crowd.integration.service.soap.client.SecurityServerClientImpl">
        <constructor-arg ref="clientProperties"/>
    </bean>

    <bean id="httpAuthenticator" class="com.atlassian.crowd.integration.http.HttpAuthenticatorImpl">
        <constructor-arg ref="securityServerClient"/>
    </bean>

    <bean id="verifyTokenFilter" class="com.atlassian.crowd.integration.http.VerifyTokenFilter" lazy-init="true">
        <constructor-arg ref="httpAuthenticator"/>
    </bean>

    <bean id="crowdAuthenticationInterceptor" class="com.atlassian.crowd.integration.xwork.CrowdAuthenticationInterceptor" lazy-init="true">
        <constructor-arg ref="httpAuthenticator"/>
    </bean> 

</beans>

To use a Spring-injected VerifyTokenFilter change the filter definition in your web.xml to:

<filter>
    <filter-name>verifyTokenFilter</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>

関連トピック

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

Crowd Documentation