Class OAuth2ClientFilter

  • All Implemented Interfaces:
    Filter

    public final class OAuth2ClientFilter
    extends Object
    implements 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=<clientId>&issuer=<issuer_name>&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 AM only.]
     "discoverySecretId"            : signing key secret id   [OPTIONAL - secret id used in private_key_jwt dynamic
                                                                          client registration.]
     "secretsProvider"              : secrets provider        [OPTIONAL - secrets provider used to obtain secrets.
                                                                          REQUIRED if 'discoverySecretId' used.]
     "tokenEndpointAuthMethod"      : string                  [OPTIONAL - defaults to 'client_secret_basic'. If
                                                                          'discoverySecretId' is set then this is always
                                                                          set explicitly to 'private_key_jwt'.]
     "tokenEndpointAuthSigningAlg"  : string                  [OPTIONAL - defaults to RS256 if 'discoverySecretId' is
                                                                          set otherwise unused.]
     }
     </pre>
    
     For example, if you want to use a nascar page (with multiple client
     registrations, defined in the "registrations" attribute):
    
     <pre>
     {@code
     {
         "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
         }
     }
     }
     </pre>
    
     This one, containing a nascar page and allowing dynamic client registration with AM:
    
     <pre>
     {@code
     {
         "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"
             }
         }
     }
     }
     </pre>
    
     Or this one, with a single client registration.
    
     <pre>
     {@code
     {
         "name": "OpenIDConnect",
         "type": "OAuth2ClientFilter",
         "config": {
             "target"                : "${attributes.openid}",
             "clientEndpoint"        : "/openid",
             "registrations"         : [ "openam" ],
             "failureHandler"        : "LoginFailed"
         }
     }
     }
     </pre>
    
     Once authorized, this filter will inject the following information into
     the target location:
    
     <pre>
     {@code
     "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"
             }
         }
     }
     
     
    • 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,
                                  PerItemEvictionStrategyCache<String,​Promise<Map<String,​Object>,​OAuth2ErrorException>> userInfoCache,
                                  org.forgerock.openig.filter.oauth2.client.UriValidationService validationService,
                                  Clock clock,
                                  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.
        validationService - The service for validating 'goto' parameters (login + logout)
        clock - The Clock to use.
        discoveryAndDynamicRegistrationChain - The chain used for discovery and dynamic client registration.
        clientEndpoint - The expression which will be used for obtaining the base URI
    • Method Detail

      • filter

        public Promise<Response,​NeverThrowsException> filter​(Context context,
                                                                   Request request,
                                                                   Handler next)
        Description copied from interface: Filter
        Filters the request and/or response of an exchange. To pass the request to the next filter or handler in the chain, the filter calls next.handle(context, request).

        This method may elect not to pass the request to the next filter or handler, and instead handle the request itself. It can achieve this by merely avoiding a call to next.handle(context, request) and creating its own response object. The filter is also at liberty to replace a response with another of its own by intercepting the response returned by the next handler.

        Specified by:
        filter in interface Filter
        Parameters:
        context - The request context.
        request - The request.
        next - The next filter or handler in the chain to handle the request.
        Returns:
        A Promise representing the response to be returned to the client.
      • 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​(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​(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.