com.atlassian.crowd.integration.http

Interface CrowdHttpAuthenticator

All Known Implementing Classes:

CacheAwareCrowdHttpAuthenticator, CrowdHttpAuthenticatorImpl

public interface CrowdHttpAuthenticator

This interface is used to manage HTTP authentication. It is the fundamental class for web/SSO authentication integration. This interface contains many convenience methods for authentication integration with existing applications. For most applications, using the following methods will be sufficient to achieve SSO:

1. authenticate: authenticate a user.
2. isAuthenticated: determine if a request is authenticated.
3. getUser: retrieve the user for an authenticated request.
4. logout: sign the user out.

Use the HttpAuthenticatorFactory to get an instance of a class, or use an IoC container (like Spring) to manage the underlying implementation as a singleton.

Method Summary

Modifier and Type	Method and Description
User	authenticate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String username, String password) Authenticates the user based on provided credentials.
User	authenticateWithoutValidatingPassword(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, String username) Authenticates the user without validating password.
AuthenticationState	checkAuthenticated(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Tests whether a request is authenticated via SSO.
String	getToken(javax.servlet.http.HttpServletRequest request) Retrieves the Crowd authentication token from the request.
User	getUser(javax.servlet.http.HttpServletRequest request) Attempts to retrieve the currently authenticated User from the request.
boolean	isAuthenticated(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Deprecated. since 2.8.3. Use checkAuthenticated(HttpServletRequest, HttpServletResponse) instead.
void	logout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Logs out the authenticated user.

Method Detail

getUser

@Nullable
User getUser(javax.servlet.http.HttpServletRequest request)
                throws InvalidTokenException,
                       ApplicationPermissionException,
                       InvalidAuthenticationException,
                       OperationFailedException

Attempts to retrieve the currently authenticated User from the request. This will attempt to find the Crowd SSO token via:

1. a request attribute (not the request parameter), OR
2. a cookie on the request

Parameters:

request - HTTP request, possibly containing a Crowd SSO cookie.

Returns:

authenticated User or null if the there is no authenticated user.

Throws:

InvalidTokenException - if the token in the request is not valid.

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for an unknown reason.

authenticate

@Nonnull
User authenticate(javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response,
                           String username,
                           String password)
                    throws ApplicationPermissionException,
                           InvalidAuthenticationException,
                           OperationFailedException,
                           ApplicationAccessDeniedException,
                           ExpiredCredentialException,
                           InactiveAccountException,
                           InvalidTokenException

Authenticates the user based on provided credentials.

Validation factors (such as IP address) are extracted from the request.

If the user is successfully authenticated, the Crowd SSO token is placed in:

1. the request: as an attribute, so the user is authenticated for the span of the request.
2. the response: as a cookie, so the user is authenticated for subsequent requests.

If the credentials fail authentication, any existing Crowd SSO token is removed from:

1. the request attribute.
2. the response as a cookie as a cookie with a max-age of 0.

Parameters:

request - request to set the Crowd SSO token

response - response to set the Crowd SSO token cookie

username - username to authenticate

password - password of the user

Returns:

the authenticated user if the authentication was successful, otherwise an exception is thrown.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for an unknown reason.

ApplicationAccessDeniedException

ExpiredCredentialException

InactiveAccountException

InvalidTokenException

authenticateWithoutValidatingPassword

@Nonnull
User authenticateWithoutValidatingPassword(javax.servlet.http.HttpServletRequest request,
                                                    javax.servlet.http.HttpServletResponse response,
                                                    String username)
                                             throws ApplicationPermissionException,
                                                    InvalidAuthenticationException,
                                                    OperationFailedException,
                                                    ApplicationAccessDeniedException,
                                                    InactiveAccountException,
                                                    InvalidTokenException

Authenticates the user without validating password.

Validation factors (such as IP address) are extracted from the request.

If the user is successfully authenticated, the Crowd SSO token is placed in:

1. the request: as an attribute, so the user is authenticated for the span of the request.
2. the response: as a cookie, so the user is authenticated for subsequent requests.

If authentication fails, any existing Crowd SSO token is removed from:

1. the request attribute.
2. the response as a cookie as a cookie with a max-age of 0.

Parameters:

request - request to set the Crowd SSO token

response - response to set the Crowd SSO token cookie

username - username to authenticate

Returns:

the authenticated user if the authentication was successful, otherwise an exception is thrown.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for an unknown reason.

ApplicationAccessDeniedException

InactiveAccountException

InvalidTokenException

isAuthenticated

@Deprecated
boolean isAuthenticated(javax.servlet.http.HttpServletRequest request,
                                    javax.servlet.http.HttpServletResponse response)
                             throws OperationFailedException

Deprecated. since 2.8.3. Use checkAuthenticated(HttpServletRequest, HttpServletResponse) instead.

Tests whether a request is authenticated via SSO. This only tests against the Crowd server if the validation interval is exceeded, this value is obtained from crowd.properties AND that there is a valid token present for the user in the Crowd Cookie. The last validated date/time attribute of the request session is updated.

Parameters:

request - HttpServletRequest

response - HttpServletResponse

Returns:

true if and only if the request has been authenticated.

Throws:

OperationFailedException - if the operation has failed for an unknown reason.

checkAuthenticated

@Nonnull
AuthenticationState checkAuthenticated(javax.servlet.http.HttpServletRequest request,
                                                javax.servlet.http.HttpServletResponse response)
                                         throws OperationFailedException

Tests whether a request is authenticated via SSO. This only tests against the Crowd server if the validation interval is exceeded, this value is obtained from crowd.properties AND that there is a valid token present for the user in the Crowd Cookie. The last validated date/time attribute of the request session is updated.

Parameters:

request - HttpServletRequest

response - HttpServletResponse

Returns:

details of whether the request is authenticated

Throws:

OperationFailedException - if the operation has failed for an unknown reason.

Since:

2.8.3

logout

void logout(javax.servlet.http.HttpServletRequest request,
            javax.servlet.http.HttpServletResponse response)
     throws ApplicationPermissionException,
            InvalidAuthenticationException,
            OperationFailedException

Logs out the authenticated user. Removes the cookie from the response and request attribute. Invalidates the token on the server.

Parameters:

request - request contains the Crowd SSO token to invalidate and hence log the user out.

response - response returns a request to remove the token cookie from the user browser.

Throws:

ApplicationPermissionException - if the application is not permitted to perform the requested operation on the server.

InvalidAuthenticationException - if the application and password are not valid.

OperationFailedException - if the operation has failed for an unknown reason.

getToken

@Nullable
String getToken(javax.servlet.http.HttpServletRequest request)

Retrieves the Crowd authentication token from the request.

Parameters:

request - request to look for the Crowd SSO token.

Returns:

value of the token if found, otherwise null.

Throws:

IllegalArgumentException - if the request is null