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] "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" } } }
-
-
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, PerItemEvictionStrategyCache<String,Promise<Map<String,Object>,OAuth2ErrorException>> userInfoCache, org.forgerock.openig.filter.oauth2.client.UriValidationService validationService, Clock clock, Handler discoveryAndDynamicRegistrationChain, Expression<String> clientEndpoint)
Constructs anOAuth2ClientFilter
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Promise<Response,NeverThrowsException>
filter(Context context, Request request, Handler next)
Filters the request and/or response of an exchange.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(Handler handler)
Sets the handler which will be invoked when authentication fails.OAuth2ClientFilter
setLoginHandler(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.
-
-
-
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 anOAuth2ClientFilter
.- Parameters:
registrations
- TheClientRegistrationRepository
that handles the registrations.userInfoCache
- The cache to store the user informations, notnull
.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 callsnext.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.
-
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", }
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 totrue
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 totrue
by default.- Parameters:
requireLogin
-true
if authentication is required for all incoming requests, orfalse
if authentication should be performed only when required (defaulttrue
.- 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.
-
-