org.forgerock.openig.filter.oauth2.client

Class OAuth2ClientFilter

java.lang.Object

org.forgerock.openig.filter.oauth2.client.OAuth2ClientFilter

All Implemented Interfaces:

org.forgerock.http.Filter

public final class OAuth2ClientFilter
extends Object
implements org.forgerock.http.Filter

A filter which is responsible for authenticating the end-user using OAuth 2.0 delegated authorization. The filter does the following depending on the incoming request URI:

• {clientEndpoint}/login?registration=<registrationName>&goto=<url> - redirects the user for authorization against the specified client registration.
• {clientEndpoint}/login?{*}discovery={input}&goto=<url> - performs issuer discovery and dynamic client registration if possible on the given user input and redirects the user to the client endpoint.
• {clientEndpoint}/logout?goto=<url> - removes authorization state for the end-user
• {clientEndpoint}/callback - OAuth 2.0 authorization call-back end-point (state encodes nonce, goto, and client registration)
• all other requests - restores authorization state and places it in the target location.

Configuration options:

 
 "target"                       : expression,             [OPTIONAL - default is ${attributes.openid}]
 "clientEndpoint"               : expression,             [REQUIRED]
 "loginHandler"                 : handler,                [REQUIRED - if zero or multiple client registrations.
                                                           OPTIONAL - if one client registration.]
 "registrations"                : [ reference or          [OPTIONAL - MUST list the client registrations
                                    inlined declaration],             which are going to be used by this client.]
 "discoveryHandler"             : handler,                [OPTIONAL - by default it uses the 'ClientHandler'
                                                                      provided in heap.]
 "failureHandler"               : handler,                [REQUIRED]
 "defaultLoginGoto"             : expression,             [OPTIONAL - default return empty page]
 "defaultLogoutGoto"            : expression,             [OPTIONAL - default return empty page]
 "requireLogin"                 : boolean                 [OPTIONAL - default require login]
 "requireHttps"                 : boolean                 [OPTIONAL - default require SSL]
 "cacheExpiration"              : duration                [OPTIONAL - default to 20 seconds]
 "executor"                     : executor                [OPTIONAL - by default uses 'ScheduledThreadPool'
                                                                      heap object]
 "metadata"                     : {                       [OPTIONAL - contains metadata dedicated for dynamic
                                                                      client registration.]
             "redirect_uris"    : [ expression ],                [REQUIRED for dynamic client registration.]
             "scopes"           : [ expression ]                 [OPTIONAL - usage with OpenAM only.]
 }
 
 

For example, if you want to use a nascar page (with multiple client registrations, defined in the "registrations" attribute):

 
 {
     "name": "OpenIDConnect",
     "type": "OAuth2ClientFilter",
     "config": {
         "target"                : "${attributes.openid}",
         "clientEndpoint"        : "/openid",
         "registrations"         : [ "openam", "linkedin", "google" ],
         "loginHandler"          : "NascarPage",
         "failureHandler"        : "LoginFailed",
         "defaultLoginGoto"      : "/homepage",
         "defaultLogoutGoto"     : "/loggedOut",
         "requireHttps"          : false,
         "requireLogin"          : true
     }
 }
 
 

This one, containing a nascar page and allowing dynamic client registration with OpenAM:

 
 {
     "name": "OpenIDConnect",
     "type": "OAuth2ClientFilter",
     "config": {
         "target"                : "${attributes.openid}",
         "clientEndpoint"        : "/openid",
         "loginHandler"          : "NascarPage",
         "registrations"         : [ "openam", "linkedin", "google" ],
         "failureHandler"        : "LoginFailed",
         "defaultLoginGoto"      : "/homepage",
         "defaultLogoutGoto"     : "/loggedOut",
         "requireHttps"          : false,
         "requireLogin"          : true,
         "metadata"              : {
             "client_name": "iRock",
             "contacts": [ "werock@example.com", "werock@forgerock.org" ],
             "scopes": [
                 "openid", "profile"
             ],
             "redirect_uris": [ "http://my.example.com:8082/openid/callback" ],
             "logo_uri": "https://client.example.org/logo.png",
             "subject_type": "pairwise"
         }
     }
 }
 
 

Or this one, with a single client registration.

 
 {
     "name": "OpenIDConnect",
     "type": "OAuth2ClientFilter",
     "config": {
         "target"                : "${attributes.openid}",
         "clientEndpoint"        : "/openid",
         "registrations"         : [ "openam" ],
         "failureHandler"        : "LoginFailed"
     }
 }
 
 

Once authorized, this filter will inject the following information into the target location:

 
 "openid" : {
         "client_registration" : "google",
         "access_token"       : "xxx",
         "id_token"           : "xxx",
         "token_type"         : "Bearer",
         "expires_in"         : 3599,
         "scope"              : [ "openid", "profile", "email" ],
         "client_endpoint"    : "http://www.example.com:8081/openid",
         "id_token_claims"    : {
             "at_hash"            : "xxx",
             "sub"                : "xxx",
             "aud"                : [ "xxx.apps.googleusercontent.com" ],
             "email_verified"     : true,
             "azp"                : "xxx.apps.googleusercontent.com",
             "iss"                : "accounts.google.com",
             "exp"                : "2014-07-25T00:12:53+0000",
             "iat"                : "2014-07-24T23:07:53+0000",
             "email"              : "micky.mouse@gmail.com"
         },
         "user_info"          : {
             "sub"                : "xxx",
             "email_verified"     : "true",
             "gender"             : "male",
             "kind"               : "plus#personOpenIdConnect",
             "profile"            : "https://plus.google.com/xxx",
             "name"               : "Micky Mouse",
             "given_name"         : "Micky",
             "locale"             : "en-GB",
             "family_name"        : "Mouse",
             "picture"            : "https://lh4.googleusercontent.com/xxx/photo.jpg?sz=50",
             "email"              : "micky.mouse@gmail.com"
         }
     }
 
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OAuth2ClientFilter.Heaplet Creates and initializes the filter in a heap environment.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_TOKEN_KEY The expression which will be used for storing authorization information in the context.

Constructor Summary

Constructors

Constructor and Description

OAuth2ClientFilter(org.forgerock.openig.filter.oauth2.client.ClientRegistrationRepository registrations, org.forgerock.util.PerItemEvictionStrategyCache<String,org.forgerock.util.promise.Promise<Map<String,Object>,OAuth2ErrorException>> userInfoCache, org.forgerock.util.time.TimeService time, org.forgerock.http.Handler discoveryAndDynamicRegistrationChain, Expression<String> clientEndpoint) Constructs an OAuth2ClientFilter.

Method Summary

Modifier and Type	Method and Description
org.forgerock.util.promise.Promise<org.forgerock.http.protocol.Response,org.forgerock.util.promise.NeverThrowsException>	filter(org.forgerock.services.context.Context context, org.forgerock.http.protocol.Request request, org.forgerock.http.Handler next)
OAuth2ClientFilter	setDefaultLoginGoto(Expression<String> endpoint) Sets the expression which will be used for obtaining the default login "goto" URI.
OAuth2ClientFilter	setDefaultLogoutGoto(Expression<String> endpoint) Sets the expression which will be used for obtaining the default logout "goto" URI.
OAuth2ClientFilter	setFailureHandler(org.forgerock.http.Handler handler) Sets the handler which will be invoked when authentication fails.
OAuth2ClientFilter	setLoginHandler(org.forgerock.http.Handler handler) Sets the handler which will be invoked when the user needs to authenticate.
OAuth2ClientFilter	setRequireHttps(boolean requireHttps) Specifies whether all incoming requests must use TLS.
OAuth2ClientFilter	setRequireLogin(boolean requireLogin) Specifies whether authentication is required for all incoming requests.
OAuth2ClientFilter	setTarget(LeftValueExpression<?> target) Sets the expression which will be used for storing authorization information in the context.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TOKEN_KEY

public static final String DEFAULT_TOKEN_KEY

The expression which will be used for storing authorization information in the context.

See Also:

Constant Field Values

Constructor Detail

OAuth2ClientFilter

public OAuth2ClientFilter(org.forgerock.openig.filter.oauth2.client.ClientRegistrationRepository registrations,
                          org.forgerock.util.PerItemEvictionStrategyCache<String,org.forgerock.util.promise.Promise<Map<String,Object>,OAuth2ErrorException>> userInfoCache,
                          org.forgerock.util.time.TimeService time,
                          org.forgerock.http.Handler discoveryAndDynamicRegistrationChain,
                          Expression<String> clientEndpoint)

Constructs an OAuth2ClientFilter.

Parameters:

registrations - The ClientRegistrationRepository that handles the registrations.

userInfoCache - The cache to store the user informations, not null.

time - The TimeService to use.

discoveryAndDynamicRegistrationChain - The chain used for discovery and dynamic client registration.

clientEndpoint - The expression which will be used for obtaining the base URI for this filter.

Method Detail

filter

public org.forgerock.util.promise.Promise<org.forgerock.http.protocol.Response,org.forgerock.util.promise.NeverThrowsException> filter(org.forgerock.services.context.Context context,
                                                                                                                                       org.forgerock.http.protocol.Request request,
                                                                                                                                       org.forgerock.http.Handler next)

Specified by:

filter in interface org.forgerock.http.Filter

setDefaultLoginGoto

public OAuth2ClientFilter setDefaultLoginGoto(Expression<String> endpoint)

Sets the expression which will be used for obtaining the default login "goto" URI. The default goto URI will be used when a user performs a user initiated login without providing a "goto" http parameter. This configuration parameter is optional. If no "goto" parameter is provided in the request and there is no default "goto" then user initiated login requests will simply return a 200 status.

Parameters:

endpoint - The expression which will be used for obtaining the default login "goto" URI.

Returns:

This filter.

setDefaultLogoutGoto

public OAuth2ClientFilter setDefaultLogoutGoto(Expression<String> endpoint)

Sets the expression which will be used for obtaining the default logout "goto" URI. The default goto URI will be used when a user performs a user initiated logout without providing a "goto" http parameter. This configuration parameter is optional. If no "goto" parameter is provided in the request and there is no default "goto" then user initiated logout requests will simply return a 200 status.

Parameters:

endpoint - The expression which will be used for obtaining the default logout "goto" URI.

Returns:

This filter.

setFailureHandler

public OAuth2ClientFilter setFailureHandler(org.forgerock.http.Handler handler)

Sets the handler which will be invoked when authentication fails. This configuration parameter is required. If authorization fails for any reason and the request cannot be processed using the next filter/handler, then the request will be forwarded to the failure handler. In addition, the target expression will be populated with the following OAuth 2.0 error information:

 
 <target> : {
     "client_registration" : "google",
     "error"               : {
         "realm"              : string,          [OPTIONAL]
         "scope"              : array of string, [OPTIONAL list of required scopes]
         "error"              : string,          [OPTIONAL]
         "error_description"  : string,          [OPTIONAL]
         "error_uri"          : string           [OPTIONAL]
     },
     // The following fields may or may not be present depending on
     // how far authorization proceeded.
     "access_token"       : "xxx",
     "id_token"           : "xxx",
     "token_type"         : "Bearer",
     "expires_in"         : 3599,
     "scope"              : [ "openid", "profile", "email" ],
     "client_endpoint"    : "http://www.example.com:8081/openid",
 }
 
 

See OAuth2Error for a detailed description of the various error fields and their possible values.

Parameters:

handler - The handler which will be invoked when authentication fails.

Returns:

This filter.

setLoginHandler

public OAuth2ClientFilter setLoginHandler(org.forgerock.http.Handler handler)

Sets the handler which will be invoked when the user needs to authenticate. This configuration parameter is required if there are more than one client registration configured.

Parameters:

handler - The handler which will be invoked when the user needs to authenticate.

Returns:

This filter.

setRequireHttps

public OAuth2ClientFilter setRequireHttps(boolean requireHttps)

Specifies whether all incoming requests must use TLS. This configuration parameter is optional and set to true by default.

Parameters:

requireHttps - true if all incoming requests must use TLS, false by default.

Returns:

This filter.

setRequireLogin

public OAuth2ClientFilter setRequireLogin(boolean requireLogin)

Specifies whether authentication is required for all incoming requests. This configuration parameter is optional and set to true by default.

Parameters:

requireLogin - true if authentication is required for all incoming requests, or false if authentication should be performed only when required (default true.

Returns:

This filter.

setTarget

public OAuth2ClientFilter setTarget(LeftValueExpression<?> target)

Sets the expression which will be used for storing authorization information in the context. This configuration parameter is required.

Parameters:

target - The expression which will be used for storing authorization information in the context.

Returns:

This filter.