JAX-RS: OAuth2

+/*]]>*/

JAX-RS: OAuth2
Introduction
Maven dependencies
Client Registration
Developing OAuth2 Servers
- Authorization Service
  - EndUser Name in Authorization Form
  - Public Clients (Devices) @@ -413,7 +413,7 @@ ModelEncryptionSupport.decryptAccessToke </jaxrs:serviceBeans> </jaxrs:server> ]]> -

AuthorizationCodeGrantService listens on a relative "/authorize" path so in this case its absolute address will be something like "http://localhost:8080/services/myapp/authorize". This address and that of AccessTokenService will be used by third-party clients.

Third Party Client Authentication

When a client requests a token from Access Token Service, it needs to get authenticated. Providing its client_id and client secret as part of Basic Authorization scheme or posting them directly as form parameters are typical options, however other authentication schemes can be supported if required.

For example, using client certificates or assertions like SAML2 Bearer or JWT is all acceptable - the only additional requirement in this case is that a given security filter processing a specific authentication scheme maps the client credentials to an actual client_id - CXF Access Token Service will check a "client _id" property on the current message context as the last resort.

Please see JAXRS OAuth2 Assertions section for more information on how it may work.

User Session Authenticity

Redirection-based Authorization Code and Implicit flows depend on end users signing in if needed during the initial redirection, challenged with the client authorization form and returning their decision. By default, CXF will enforce the user session authenticity by keeping the session state in a servlet container's HTTPSession. If the alternative storage is preferred then you can register a new SessionAuthenticityTokenProvider (available from CXF 2.6.4) with either Authorizatio nCodeGrantService or ImplicitGrantService beans.

Customizing End User Subject initialization

By default, redirection based authorization services will the the current CXF SecurityContext to initialize a subject representing the authenticated resource owner/end user. If the customization if needed: custom CXF filter can be used to create UserSubject and set it on the message or org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface implementation can be registered with either AuthorizationCodeGrantService or ImplicitGrantService.

Protecting resources with OAuth filters

OAuthRequestFilter request handler can be used to protect the r esource server when processing the requests from the third-party clients. Add it as a jaxrs:provider to the endpoint which deals with the clients requesting the resources.

When checking a request like this:

+

AuthorizationCodeGrantService listens on a relative "/authorize" path so in this case its absolute address will be something like "http://localhost:8080/services/myapp/authorize". This address and that of AccessTokenService will be used by third-party clients.

Third Party Client Authentication

When a client requests a token from Access Token Service, it needs to get authenticated. Providing its client_id and client secret as part of Basic Authorization scheme or posting them directly as form parameters are typical options, however other authentication schemes can easily be supported if required.

For example, using client certificates or assertions like SAML2 Bearer or JWT is all acceptable - the only additional requirement in this case is that a given security filter processing a specific authentication scheme maps the client credentials to an actual client_id - CXF Access Token Service will check a "client_id" property on the current message context as the last resort. Note that org.apache.cxf.rs.security.oauth2.provider.ClientIdProvider can be registered with AccessTokenService to facilitate the mapping between an authenticated client and its id expected by the data provider if the container or filter based authentication can not set a "client_id" contextual property.

If a Basic authentication scheme is used and neither the container or filter has authenticated the client AccessTokenService will request a Client from the data provider and compare the Client's secret against the password found in the Basic scheme data. org.apache.cxf.rs.security.oauth2.provider.ClientSecretVerifier is available starting from CXF 3.0.3 to support Clients saving only password hashes. Its org.apache.cxf.rs.security.oauth2.provider.ClientSecretHashVerifier (calculates a SHA-256 password hash and compares it with the Client's secret) or custom implementations can be registered with AccessToke nService.

If a 2-way TLS is sued to authenticate a client and Client has a Base64 encoded representations of its X509Certificates available in its "applicationCertificates" property then AccessTokenService will do the additional comparison of these certificates against the ones available in the current TLS session.

Please see JAXRS OAuth2 Assertions section for more information on how it may work.

User Session Authenticity

Redirection-based Authorization Code and Implicit flows depend on end users signing in if needed during the initial redirection, challenged with the client authorization form and returning their decision. By default, CXF will enforce the user session authenticity by keeping the session state in a servlet container's HTTPSession. If the alternative storage is preferred then you can register a new SessionAuthenticityTokenProvider (available from CXF 2.6.4) with either AuthorizationCodeGrantService or ImplicitGrantService beans.

Customizing End User Subject initialization

By default, redirection based authorization services will the the current CXF SecurityContext to initialize a subject representing the authenticated resource owner/end user. If the customization if needed: custom CXF filter can be used to create UserSubject and set it on the message or org.apache.cxf.rs.security.oauth2.provider.SubjectCreator interface implementation can be registered with either AuthorizationCodeGrantService or ImplicitGrantService.

Protecting resources with OAuth filters

OAuthRequestFilter request handler can be used to protect the resource server when processing the requests from the third-party clients. Add it as a jaxrs:provider to the endpoint which deals with the clients requesting the resources.

When checking a request like this:

-

Note that no "_s" or "_search" query parameter is available, the whole query string starting after "?" represents an actual FIQL expression.
Please use "search.use.all.query.component" contextual property for this option be supported.

Alternatively the expressions can be encoded as URI path segments, see the sections below for more information.

Open Data Protocol

CXF 3.0.0-milestone2 supports the $filter query defined as part of Open Data Protocol, courtesy of Apache Olingo.

The $filter query can have a number of the logical operator s, here is a summary of the operators supported in scope of Search API:

Operator	Description
"eq"	Equal
"ne"	Not Equal
"lt"	Less Than
"le"	Less or Equal
"gt"	Greater Than< /p>
"ge"	Greater or Equal
"and"	AND
"or"	OR

Please see the specification text for some examples.

Please note that OData protocol is not supported by CXF Search API, only the $filter query is supported (only logical operators for now) for querying the application data with CXF Search API. Users should work directly with Apache Olingo to get the OData protocol supported as part of the application flow.

Some of the following examples on this page may often refer to FIQL due to the fact FIQL has been supported for a long time, but the same examples will work with OData $filter expressions. For example, replace the "_s=name==CXF" query with "$filter=name eq CXF".

Please use a "search.query.parameter.name" contextual property to indicate to the runtime that a $filter query option need to be checked for the query expression and a "search.parser" property to point to the instance of org.apache.cxf.jaxrs.ext.search.odata.ODataParser, as shown in this test, see the startServers functio n.

And here is also an XML Spring configuration example (using SearchBean in this specific case):

-
-

Also note that Apache Olingo offers its own visitor model which can be used to work with JPA2, etc.

When to use advanced queries.

Consider a typical query expression such as "a=avalue&c=cvalue". This can mean either "find all resources with 'a' and 'c' properties equal to 'avalue' and 'cvalue'" or "find all resources with 'a' or 'c' properties equal to 'avalue' and 'cvalue'". It is application specific on whether it is "and" or "or" as far as the combination of multiple query properties is concerned.

It is also to capture conditional expressions with the custom language, example, "find all resource with 'a' property less than 123" when a number of properties is large or the entities which can be searched are created dynamically.

Use FIQL or OData for capturing simple or medium complexity queries, ty pically in cases where a set of properties that a user can specify is well-known. Example, a book store resource will let users search books given a number of useful properties(those of Book and/or Library a given book is available in, etc).

Furthermore, consider using FIQL/OData and SearchConditionVisitor for the purpose of generalizing the search code, when the number of properties and entities is large, dynamic, etc.

Dependencies and Configuration

The following dependency is required starting from CXF 2.6.0:

+

Note that no "_s" or "_search" query parameter is available, the whole query string starting after "?" represents an actual FIQL expression.
Please use "search.use.all.query.component" contextual property for this option be supported.

Alternatively the expressions can be encoded as URI path segments, see the sections below for more information.

Open Data Protocol

CXF 3.0.0-milestone2 supports the $filter query defined as part of Open Data Protocol, courtesy of Apache Olingo.

The $filter query can have a number of the logical operator s, here is a summary of the operators supported in scope of Search API:

Operator	Description
"eq"	Equal
"ne"	Not Equal
"lt"	Less Than
"le"	Less or Equal
"gt"	Greater Than< /p>
"ge"	Greater or Equal
"and"	AND
"or"	OR

Please see the specification text for some examples.

Please note that OData protocol is not supported by CXF Search API, only the $filter query is supported (only logical operators for now) for querying the application data with CXF Search API. Users should work directly with Apache Olingo to get the OData protocol supported as part of the application flow.

Some of the following examples on this page may often refer to FIQL due to the fact FIQL has been supported for a long time, but the same examples will work with OData $filter expressions. For example, replace the "_s=name==CXF" query with "$filter=name eq CXF".

When to use advanced queries.

Consider a typical query expression such as "a=avalue&c=cvalue". This can mean either "find all resources with 'a' and 'c' properties equal to 'avalue' and 'cvalue'" or "find all resources with 'a' or 'c' properties equal to 'avalue' and 'cvalue'". It is application specific on whether it is "and" or "or" as far as the combination of multiple query properties is concerned.

It is also to capture conditional expressi ons with the custom language, example, "find all resource with 'a' property less than 123" when a number of properties is large or the entities which can be searched are created dynamically.

Use FIQL or OData for capturing simple or medium complexity queries, typically in cases where a set of properties that a user can specify is well-known. Example, a book store resource will let users search books given a number of useful properties(those of Book and/or Library a given book is available in, etc).

Furthermore, consider using FIQL/OData and SearchConditionVisitor for the purpose of generalizing the search code, when the number of properties and entities is large, dynamic, etc.

Dependencies and Configuration

The following dependency is required starting from CXF 2.6.0:

-

OData

Please work with Apache Olingo to produce OData queries from the code.

Using dates in queries

By default, the date values have to have the following format: "yyyy-MM-dd", for example:

+

Using dates in queries

By default, the date values have to have the following format: "yyyy-MM-dd", for example:

A custom date format can be supported. Use "search.date-format" contextual property, example, "search.date-format"="yyyy-MM-dd'T'HH:mm:ss" will let users type:

@@ -937,7 +927,19 @@ FiqlSearchConditionBuilder bCustom = new
 String ret = bCustom.is("foo").equalTo(d).query();
 assertEquals("foo==2011-03-01T12:34:00", ret);
 ]]>
-

Alternative query languages

Custom org.apache.cxf.jaxrs.ext.search.SearchConditionParser implementations can be registered as a "search.parser" contextual property starting from CXF 3.0.0-milestone2.

Content Extraction

Starting from CXF 3.0.2, the content extraction support has been added in order to complement the search capabilites with text extraction from various document formats (PDF, ODF, DOC,TXT,RTF,...). It is based on Apache Tika and is available in two shapes: raw content extraction (TikaContentExtractor) and Lucene document content extraction (TikaLuceneContentExtractor).

Using TikaContentExtractor

The purpose of Tika content extractor is to provide the essential support of text extraction from supported document formats. Additionally, the metadata is being extracted as well depending on the doc ument format (author, modified, created, pages, ...). The TikaContentExtractor accepts the list of supported parsers and returns the extracted metadata together with the desired extracted content format (by default raw text). For example:

+

Alternative query languages

Custom org.apache.cxf.jaxrs.ext.search.SearchConditionParser implementations can be registered as a "search.parser" contextual property starting from CXF 3.0.0-milestone2.

OData

Please use a "search.query.parameter.name" contextual property to indicate to the runtime that an OData '$filter' query option needs to be checked for the query expression and a "search.parser" property to point to the instance of org.apache.cxf.jaxrs.ext.search.odata.ODataParser, as shown in this test, see the startServers function.

And here is also an XML Spring configuration example (using SearchBean in this specific case):

+
+

Also note that Apache Olingo offers its own visitor model which can be used to work with JPA2, etc.

Content Extraction

Starting from CXF 3.0.2, the content extraction support has been added in order to complement the search capabilites with text extraction from various document formats (PDF, ODF, DOC,TXT,RTF,...). It is based on Apache Tika and is available in two shapes: raw content extraction (TikaContentExtractor) and Lucene document content extraction (TikaLuceneContentExtractor).

Using TikaContentExtractor

The purpose of Tika content extractor is to provide the essential support of text extraction from supported document formats. Additionally, the metadata is being extracted as well depending on the document format (author, modified, created, pages, ...). The TikaContentExtractor accepts the list of supported parsers and returns the extracted metadata together with the desired extracted content format (by default raw text). For example:

By default, the TikaContentExtractor also performs the content type detection and validation, which could be turned off using the 'validateMediaType' constructor argument.

Using TikaLuceneContentExtractor

The TikaLuceneContentExtractor is very similar to TikaContentExtractor but instead of raw content and metadata it returns prepared Lucene document. However, in order to properly create the Lucene document which is ready to be indexed, TikaLuceneContentExtractor accepts an additional parameter, LuceneDocumentMetadata, with the field types and type converters. For example: