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 Description

static class OAuth2ClientFilter.Heaplet
Creates and initializes the filter in a heap environment.

Field Summary

Fields
Modifier and Type Field Description

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

Constructor Summary

Constructors
Constructor	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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	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.

Class OAuth2ClientFilter

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_TOKEN_KEY

Constructor Detail

OAuth2ClientFilter

Method Detail

filter

setDefaultLoginGoto

setDefaultLogoutGoto

setFailureHandler

setLoginHandler

setRequireHttps

setRequireLogin

setTarget