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

Class AuthorizationCodeOAuth2ClientFilter

java.lang.Object
org.forgerock.openig.filter.oauth2.client.AuthorizationCodeOAuth2ClientFilter
All Implemented Interfaces:
Filter
public final class AuthorizationCodeOAuth2ClientFilter 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 dedicated context.

Configuration options: 

 
 "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,                [OPTIONAL - Sets the handler which will be invoked when
                                                                      authentication fails.
                                                                      Default to rethrow the exception if any.]
 "defaultLoginGoto"             : expression,             [OPTIONAL - Sets the expression which will be used for
                                                                      obtaining the default login "goto" URI.
                                                                      Defaults to an HTTP 200 response]
 "defaultLogoutGoto"            : expression,             [OPTIONAL - Sets the expression which will be used for
                                                                      obtaining the default logout "goto" URI.
                                                                      Default to an HTTP 200 response]
 "requireLogin"                 : boolean                 [OPTIONAL - Specifies whether authentication is required for
                                                                      all incoming requests. Defaults to true.]
 "requireHttps"                 : boolean                 [OPTIONAL - Specifies whether all incoming requests must use
                                                                      TLS. Default to true.]
 "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.]
             "pkce_method"      : [ boolean ]                    [OPTIONAL - set the Proof Key for Code Exchange
                                                                             (PKCE) method, 'none' or 'S256'.
                                                                             Defaults to 'S256'.]
 "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.]

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

 
 {
     "name": "OpenIDConnect",
     "type": "AuthorizationCodeOAuth2ClientFilter",
     "config": {
         "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 AM: 

 
 {
     "name": "OpenIDConnect",
     "type": "AuthorizationCodeOAuth2ClientFilter",
     "config": {
         "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": "AuthorizationCodeOAuth2ClientFilter",
     "config": {
         "clientEndpoint"        : "/openid",
         "registrations"         : [ "openam" ],
         "failureHandler"        : "LoginFailed"
     }
 }

Once authorized, this filter will inject the following information into either OAuth2InfoContext or OAuth2FailureContext, depending on the outcome of the authorization attempt.

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