Page History

...

AccessTokenService

The role of AccessTokenService is to exchange a token grant for a new access token which will be used by the client to access the end user's resources.
Here is an example request log:

...

After validating the request, the service will find a matching AccessTokenGrantHandler and request to create a ServerAccessToken which is a server-side representation of the access token.
The grant handlers, such as AuthorizationCodeGrantHandler may delegate the creation of the actual access token to data providers, which may will create Bearer or MAC access tokens with the help of utility classes shipped with CXF or depend on other 3rd party token libraries.

The data providers do not strictly required to persist the data such as access tokens, instead the token key may act as an encrypted bag capturing all the relevant information.

Note that AccessTokenService may not need to have AccessTokenGrantHandler injected - if it finds out that the data provider is AuthorizationCodeDataProvider then it will create AuthorizationCodeGrantHandler itself. This will work well unless AuthorizationCodeGrantHandler itself needs to be customized and thus directly injected into AccessTokenService.

Now that the token has been created, it is mapped by the service to a client access token representation and is returned back as a JSON payload:

...

As mentioned above, AccessTokenService can work with whatever token is created by a given data provider. This section provides more information on how CXF may help with supporting Bearer and MAC tokensother token types.

Bearer

The following code fragment shows how a BearerAccessToken utility class can be used to create Bearer tokens:

...

CustomOAuthDataProvider will also be asked by OAuthRequestFilter to validate the incoming Bearer tokens given that they typically act as database key or key alias, if no Bearer token validator is registered.

Note that all the default providers shipped with CXF create and persist Bearer access tokens themselves.

HAWK

Starting from CXF 3.0.0-milestone2 the Hawk scheme is supported instead of MAC (described in the next section). The way it is supported is identical to the way MAC scheme is supported in earlier CXF versions. The only differences are: 'Hawk' replaces 'Mac' in the Authorization header, the Hawk token returned by the server will have 'secret' and 'algorithm' parameters instead of 'mac_key' and 'mac_algorithm' parameters.

...

The text below applies to CXF up to 3.0.0-milestone2. Starting from 3.0.0-milestone2 MAC scheme is not supported, see above about the Hawk scheme. Support for the MAC scheme will be re-introduced once the OAuth2 working group finishes this effortSee also OAuth2 Proof Of Possession Tokens which will be supported in CXF in the future.

CXF 2.6.2 supports MAC tokens as specified in the latest MAC Access Authentication draft created by Eran Hammer and others. MAC tokens offer an option for clients to demonstrate they 'hold' the token secret issued to them by AccessTokenService.
It is recommended that AccessTokenService endpoint issuing MAC tokens enforces a two-way TLS for an extra protection of the MAC token data returned to clients.

...

where 'ts' attribute is used to pass a timestamp value.

Encrypted

...

and Signed Tokens

Typically, the tokens are persisted in the storage. The alternative approach is to completely encrypt the token state and return the encrypted representation back to a client: the processing time to do with the encryption and decryption might increase but the server wins on avoiding the DB / storage lookups.    

...

The tokens can be encrypted and decrypted with symmetric (secret) keys or certificates (public and private keys) and the combination of certificates and secret keys.

ModelEncryptionSupport can be used to encrypt the tokens using the custom serialization format. EncryptionUtils can be used directly if the alternative serialization format is preferred.  

Note that ServerAuthorizationGrant and Client can also be encrypted.

...

The simplest strategy is to encrypt and decrypt the tokens with the symmetric/secret keys. Every new token can be encrypted with a unique secret key or all of them can be encrypted with a single secret key. The utilities provide few methods for creating secret keys with the default and advanced properties, in addition there are many examples around on how to create the keys with the specific properties.

...

SecretKey key = EncryptionUtilsCryptoUtils.getSecretKey();

// create a new token, encrypt its state and return

ServerAccessToken token = new BearerAccessToken(client, 3600L);

String encryptedToken = ModelEncryptionSupport.encryptAccessToken(token, key);

token.setTokenKey(encryptedToken);

return token;

// decrypt a token given a token key

ModelEncryptionSupport.decryptAccessToken(this, encryptedToken, key);

Using Certificates

Working with the certificates to encrypt the state is similar to working with the symmetric keys. Please check the code examples in EncryptionsUtilsTest.

One needs to load a Certificate, use its public key to encrypt and the private key to decrypt. using the certificate to encrypt the whole serialized token representation might be marginally slower compared to using the symmetric keys, however given that the sequence is about 300+ characters maximum the performance can be reasonable.

Using Certificates and Secret Keys

The other approach is to generate a secret key, use this key to encrypt the token and then use the certificate to encrypt the key. The encrypted token and the actual encrypted secret key can be returned to the client as a token parameter, for example, as a 'key' parameter. This 'key' parameter will need to be returned to the OAuth2 server, via the HTTP header or the custom authorization scheme. The data providers using this mechanism will need to implement AccessTokenValidator and decrypt the encrypted key with the private certificate key, and decrypt the token with the decrypted secret key. Please check the code example in EncryptionsUtilsTest.

Encrypted JWT Tokens

Encrypted and Signed JWT Tokens

JWT Token JWT Token can be JWE-encrypted and the encrypted string passed to ServerAccessToken as access token id parameter.

See JAX-RS JoseJOSE wiki page for more information on how to sign and encrypt JSON Web Tokens.

JwtAccessTokenUtils provides utility method for encrypting and decrypting an access token represented as JWT.

Note more support for JWT access tokens is on the way.

Custom tokens

If needed, users can use their own custom token types, with the only restriction that the custom token type implementations have to extend org.apache.cxf.rs.security.oauth2.common.ServerAccessToken.

...

Alternatively, if you prefer, a custom MessageBodyWriter implementation can be registered instead. 

Access Token Validation Service

AccessTokenValidatorService

The AccessTokenValidatorService is a CXF specific OAuth2 service for accepting the remote access token validation requests. OAuthRequestFilter needs to be injected with AccessTokenValidatorClient which will ask AccessTokenValidatorService to return the information relevant to the current access token, before setting up a security context. More on it below.

TokenIntrospectionService

The TokenIntrospectionService is a standard OAuth2 service for accepting the remote access token introspection requests. See RFC 7662. OAuthRequestFilter needs to be injected with AccessTokenIntrospectionClient.

TokenRevocationService

TokenRevocationService is a simple OAuth2 service supporting the clients wishing to revoke the access or refresh tokens they own themselves, please see OAuth2 Token Revocation Draft for more information.

...