2.5. HTTP Authentication

Prev
PicketLink Reference Documentation
Next

⁠2.5. HTTP Authentication

PicketLink supports the following HTTP Authentication Schemes:

BASIC
DIGEST
FORM
CLIENT-CERT

It also provides a very flexible and configurable API if you want to create your own custom authentication scheme.

This functionality is enabled by a specific JEE Servlet Filter, the org.picketlink.authentication.web.AuthenticationFilter, which behind the scenes delegates the authentication to the Identity bean. Once a client is authenticated you can use the Identity as usual:

@Inject
private Identity identity;

public void someMethod() {
    Account account = this.identity.getAccount();
	
	  // deal with the authenticated account
}

The next sections will describe how to configure the authentication filter for your application and describe each of these built-in authentication schemes individually.

Report a bug

⁠2.5.1. Authentication Filter

To enable HTTP Authentication to your application, you first need to configure the org.picketlink.authentication.web.AuthenticationFilter in WEB-INF/web.xml as follows:

<filter>
  	<filter-name>AuthenticationFilter</filter-name>
  	<filter-class>org.picketlink.authentication.web.AuthenticationFilter</filter-class>
  	
	<!-- Configure HTTP BASIC Authentication Scheme -->
  	<init-param>
        	<param-name>authType</param-name>
        	<param-value>BASIC</param-value>
    	</init-param>
</filter>

<!-- Defines which URLs should be protected by this filter -->
<filter-mapping>
	<filter-name>AuthenticationFilter</filter-name>
  	<url-pattern>/*</url-pattern>
</filter-mapping>

When you enable the AuthenticationFilter, the URLs defined by filter-mapping are protected and requests are processed as follows:

1. The AuthenticationFilter checks if the request came from an authenticated client.
2. If the client is not authenticated, he will be challenged for credentials. Is up to the configured authentication scheme (eg.: BASIC, DIGEST, FORM or CLIENT-CERT) to decide how the client should be challenged for credentials.
3. Once the client provides the credentials and send them in another request, the AuthenticationFilter will ask the authentication scheme to extract the credentials. At this momment the DefaultLoginCredentials bean is populated with the credential.
4. The AuthenticationFilter now invokes the Identity bean login method to authenticate the client using the provided credentials.
5. If authentication is successful, the AuthenticationFilter continues to process the request. Otherwise, go to step 2.

There are some configuration options you can specify in order to change the AuthenticationFilter default behavior. These options are specified as init-param elements within the filter configuration.

⁠

Table 2.2. Initialization Parameters

Configuration	Description
`authType`	Specifies the HTTP Authentication Scheme. Possible values are: `FORM`, `BASIC`, `DIGEST`, `CLIENT_CERT` and `TOKEN`.
`unprotectedMethods`	Specifies which HTTP Methods are not protected by the filter. A comma-separated list of strings representing the methods you don't want to protect. Eg.: `OPTIONS`.
`forceReAuthentication`	Forces client authentication, even if already authenticated. In this case, the authentication filter will logout the client first and authenticate him again. Possible values are `true` or `false`.

The initialization parameters must be defined as follows:

<filter>
  	<filter-name>AuthenticationFilter</filter-name>
  	<filter-class>org.picketlink.authentication.web.AuthenticationFilter</filter-class>
  	
	<!-- Configure HTTP BASIC Authentication Scheme -->
  	<init-param>
        	<param-name>authType</param-name>
        	<param-value>BASIC</param-value>
    	</init-param>
    	
  	<!-- OPTIONS requests are not protected. Eg.: CORS Pre-flight requests. -->
  	<init-param>
        	<param-name>unprotectedMethods</param-name>
        	<param-value>OPTIONS</param-value>
    	</init-param>
</filter>

<!-- Defines which URLs should be protected by this filter -->
<filter-mapping>
	<filter-name>AuthenticationFilter</filter-name>
  	<url-pattern>/*</url-pattern>
</filter-mapping>

Report a bug