Package org.forgerock.openig.filter.oauth2.client

Class OAuth2ClientFilter

java.lang.Object
org.forgerock.openig.filter.oauth2.client.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]
 "prompt"                       : string                  [OPTIONAL - when provided, passed to the AS in the
                                                                      authorization redirect.]
 "revokeOauth2TokenOnLogout"    : boolean                 [OPTIONAL - set to true to revoke the access/refresh token
                                                                      during user initiated logout. Defaults to false]
 "openIdEndSessionOnLogout"     : boolean                 [OPTIONAL - set to true to redirect to the OpenID
                                                                      'end_session' endpoint, if it is defined,
                                                                      during user initiated logout. Defaults to false]
 "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 - if unset then defaults to 'client_secret_basic',
                                                                      unless 'discoverySecretId' is set when it will
                                                                      default to 'private_key_jwt' instead.]
 "tokenEndpointAuthSigningAlg"  : string                  [OPTIONAL - defaults to RS256 if 'discoverySecretId' is
                                                                      set otherwise unused.]
 "oAuth2SessionKey              : string                  [OPTIONAL - the key to store the OAuth2 session inside the
                                                                      IG session.
                                                                      Defaults to the complete client endpoint URI.]
 }
 </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 Details

    • 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:

  • Constructor Details

  • Method Details

    • 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.

    • setRevokeOauth2TokenOnLogout

      public OAuth2ClientFilter setRevokeOauth2TokenOnLogout(boolean revokeOauth2TokenOnLogout)
      Enables revoking the access/refresh token during logout.
      Parameters:
      revokeOauth2TokenOnLogout - Set to true to enable, false by default.
      Returns:
      this filter

    • setOpenIdEndSessionOnLogout

      public OAuth2ClientFilter setOpenIdEndSessionOnLogout(boolean openIdEndSessionOnLogout)
      Enables redirecting to the end_session endpoint during logout.
      Parameters:
      openIdEndSessionOnLogout - Set to true to enable, false by default.
      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.