This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Extension Points for OAuth

Owned by Former user (Deleted)
Last updated: Nov 27, 2019 by Gomathy Kumarakuruparan (Unlicensed)
5 min read

This topic includes a list of all the WSO2 Identity Server extension points related to OAuth and OpenID Connect (OIDC).

Implementing an OAuth Extension

Any OAuth extension listed below can be implemented, by implementing an interface or extending an abstract class as defined under each extension point.
When the implementation is done, package your classes as a .jar file and place it in the <IS_HOME>/repository/component/lib directory.
Then configure your extension in <IS_HOME>/repository/conf/identity/identity.xml file under the <OAuth> element referring to the 'Configuration' section of the respective extension point below.
Restart the server to effect changes.

The following are the available OAuth/OIDC extension points.

OAuth Grant Handler 

UsageThis extension point is useful when you want to support an OAuth flow that is different from standard grant types. This extension point validates the grant, scopes, and access delegation.
Interfaceorg.wso2.carbon.identity.oauth2.token.handlers.grant.AuthorizationGrantHandler
Abstract Classorg.wso2.carbon.identity.oauth2.token.handlers.grant.AbstractAuthorizationGrantHandler
Configuration
<SupportedGrantTypes>
	...
	<SupportedGrantType>
    	<GrantTypeName>grant type identifier </GrantTypeName>
    	<GrantTypeHandlerImplClass>full qualified class name of grant handler</GrantTypeHandlerImplClass>
	</SupportedGrantType>
</SupportedGrantTypes>
SampleSee Writing a Custom OAuth 2.0 Grant Type for a sample implementation of this extension point.

OAuth Grant Validator

Usage

This extension point can be used to implement a grant validator that validates the grant request sent to the '/oauth2/token' endpoint. Request parameters and headers can be validated by implementing this extension point.
If a new grant type is being implemented and defined with a new grant type identifier with the OAuth Grant Handler extension, you must also implement a grant validator and register that against the same grant type identifier from the identity.xml.
If a supported grant type is to be modified you may implement a grant validator if needed, otherwise supported grant type validators can be reused.

Abstract Classorg.apache.oltu.oauth2.common.validators.AbstractValidator
Configuration
<SupportedGrantTypes>
	...
	<SupportedGrantType>
    	<GrantTypeName>grant type identifier </GrantTypeName>
    	<GrantTypeHandlerImplClass>full qualified class name of grant handler</GrantTypeHandlerImplClass>
    	<GrantTypeValidatorImplClass>full qualified class name of grant validator</GrantTypeValidatorImplClass>
	</SupportedGrantType>
</SupportedGrantTypes>

Client Authentication Handler

UsageThis extension point can be used when the client credential authentication needs to be customized when issuing tokens. By default the Identity Server validates the client id and secret.
Interfaceorg.wso2.carbon.identity.core.handler.AbstractIdentityHandler
Abstract Classorg.wso2.carbon.identity.oauth2.client.authentication.AbstractOAuthClientAuthenticator
Default Implementation

org.wso2.carbon.identity.oauth2.token.handlers.clientauth.BasicAuthClientAuthHandler

Configuration
<EventListener type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"  name="full qualified name of client authentication handler" orderId="order Id" enable="true">  <Property name="name">property value</Property>
</EventListener>

OAuth Token Generator

Usage

This extension point can be used to change the access token, refresh token, authorization code generation logic as preferred. By default a UUID will be generated as the token value.

This extension point can be used to generate a self-contained access token, that contains all the information which are required to validate the token and the user profile information by itself.
For example, a JWT with a payload as below, can be used as a self contained access token, followed by the signature of the token issuer.

{
 “sub” : “larry”,
 “scp” : [ “openid”, “email”, “app:write” ],
 “iss” : “http://idp.example.com",
 “iat” : 1360050795,
 “exp” : 1360053600,
}

For more information on implementing a self contained access token, as an extension to the WSO2 Identity Server, refer this blog.


Interfaceorg.wso2.carbon.identity.oauth2.token.OauthTokenIssuer
Default Implementation

org.wso2.carbon.identity.oauth2.token.OauthTokenIssuerImpl

Configuration
<IdentityOAuthTokenGenerator>full qualified class name of oauth token generator</IdentityOAuthTokenGenerator>

OAuth Callback Handler

UsageThis extension point is provided to verify whether the authenticated user is the rightful owner of the resource. There can be multiple active OAuthCallbackHandler implementations at a given time. These are registered through the identity.xml file. In run-time, each and every authorization callback handler is invoked to see whether it can handle the given callback. Then the callback with the highest priority is chosen. After handling the callback, the Identity Server can set whether the given callback is authorized or not.
Interfaceorg.wso2.carbon.identity.oauth.callback.OAuthCallbackHandler
Abstract Classorg.wso2.carbon.identity.oauth.callback.AbstractOAuthCallbackHandler
Default Implementationorg.wso2.carbon.identity.oauth.callback.DefaultCallbackHandler
Configuration
<OAuthCallbackHandlers>
	...
	<OAuthCallbackHandler Class="full qualified class name of the oauth call back handler">
		<Priority>an integer value defining priority</Priority>
		<Properties>
			...
			<Property Name="property name">property value</Property>
			...
		</Properties>
	</<OAuthCallbackHandler>
</OAuthCallbackHandlers>

Token Persistence Processor

Usage

This extension point can be used to process keys and secrets just before storing them in the database. For example you may need to persist encrypted tokens in the database, in which you can use this extension to encrypt tokens before storing them in the database and to decrypt when retrieving back from database.

If a token persistence processor is to be engaged, it is recommended to configure the respective token processor with the very first configuration of the product. Otherwise already persisted data may need to be migrated to the new format later.

Interfaceorg.wso2.carbon.identity.oauth.tokenprocessor.TokenPersistenceProcessor
Default Implementation


org.wso2.carbon.identity.oauth.tokenprocessor.PlainTextPersistenceProcessor


Other Available Implementations

org.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor

Note: To enable OAuth token hashing and encryption, see Setting Up OAuth Token Encryption.

Configuration
<TokenPersistenceProcessor>full qualified class name of the token persistence processor</TokenPersistenceProcessor>

OAuth2 Token Validator

Usage

This extension point can be used if token validation and scope validation needs to be customized when invoking the token validation endpoint. Token validators can be registered per token type such as 'bearer'.
A default implementation that supports for 'bearer' token type is available.

Interfaceorg.wso2.carbon.identity.oauth2.validators.OAuth2TokenValidator
Default implementationorg.wso2.carbon.identity.oauth2.validators.DefaultOAuth2TokenValidator
Configuration
<TokenValidators>
	<TokenValidator type="token type" class="full qualified class name of the oauth2 token validator"/>
</TokenValidators>

AuthorizationContext Token Generator 

Usage

This extension point can be used to customize the token that can be generated relevant to the authorization context by invoking the token validation endpoint.
By default, a JWT token generation implementation is supported with following properties encoded to each token validation request.

  • subscriber, applicationName, apiContext, version, tier, and endUserName
  • Additional properties can be encoded by engaging a claims retriever.
  • The JWT header and body are base64 encoded separately and concatenated with a dot

Finally the token is signed using SHA256 with RSA algorithm.

Interfaceorg.wso2.carbon.identity.oauth2.authcontext.AuthorizationContextTokenGenerator
Default Implementationorg.wso2.carbon.identity.oauth2.authcontext.JWTTokenGenerator
Configuration
<AuthorizationContextTokenGeneration>
	...
   	<TokenGeneratorImplClass>full qualified class name of the authorization context token generator</TokenGeneratorImplClass>
    ...
</AuthorizationContextTokenGeneration>

For more infomation on above configuration refer here.

Claims Retriever

Usage

This extension point can be used if additional claims or properties needs to be engaged to the JWT token generated in the token validation response as explained in extension point above.
The default implementation reads user claim values from the default Carbon user store.

Interfaceorg.wso2.carbon.identity.oauth2.authcontext.ClaimsRetriever
Default Implementationorg.wso2.carbon.identity.oauth2.authcontext.DefaultClaimsRetriever
Configuration
<AuthorizationContextTokenGeneration>
	...
    <ClaimsRetrieverImplClass>full qualified class name of the claims retriever</ClaimsRetrieverImplClass>
    ...
</AuthorizationContextTokenGeneration>

For more infomation on above configuration refer here.

Response Type Handler

Usage

This is intended to perform access delegation, scope validation and to issue tokens based on token type such as 'code', 'token' etc. Multiple implementations can be registered upon the token type.
This extension can be used if a specific token type needs to be supported or customized.

Interfaceorg.wso2.carbon.identity.oauth2.authz.handlers.ResponseTypeHandler
Abstract Classorg.wso2.carbon.identity.oauth2.authz.handlers.AbstractResponseTypeHandler
Available Implementations

org.wso2.carbon.identity.oauth2.authz.handlers.CodeResponseTypeHandler
org.wso2.carbon.identity.oauth2.authz.handlers.TokenResponseTypeHandler

Configuration
<SupportedResponseTypes>
	...
    <SupportedResponseType>
    	<ResponseTypeName>token</ResponseTypeName>
        <ResponseTypeHandlerImplClass>full qualified class name of the response type handler</ResponseTypeHandlerImplClass>
    </SupportedResponseType>
</SupportedResponseTypes>

UserInfo Access Token Validator

Usage

This extension point can be used if access token validation, when accessing '/oauth2/userinfo' resource, needs to be changed.
By default, the access token issued is validated against the token validation service and 'scope' request parameter is validated to have 'openid' scope.

Interfaceorg.wso2.carbon.identity.oauth.user.UserInfoAccessTokenValidator
Default implementationorg.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoISAccessTokenValidator
Configuration
<UserInfoEndpointAccessTokenValidator>full qualified class name of the userinfo access token validator</UserInfoEndpointAccessTokenValidator>

UserInfo Claim Retriever

Usage

This extension point can be used if the user claim set returned when invoking '/oauth2/userinfo' resource needs to be modified.

Interfaceorg.wso2.carbon.identity.oauth.user.UserInfoClaimRetriever
Default implementationorg.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoUserStoreClaimRetriever
Configuration
<UserInfoEndpointClaimRetriever>full qualified class name of the userinfo claim retriever</UserInfoEndpointClaimRetriever>

UserInfo Request Validator

Usage

This extension point can be used if the request validation logic, for requests initiated for '/oauth2/userinfo', needs to be changed. 

The default behavior is validating the schema and authorization header according to the specification.

Interfaceorg.wso2.carbon.identity.oauth.user.UserInfoRequestValidator
Default implementationorg.wso2.carbon.identity.oauth.endpoint.user.impl.UserInforRequestDefaultValidator
Configuration
<UserInfoEndpointRequestValidator>full qualified class name of the userinfo endpoint request validator</UserInfoEndpointRequestValidator>

UserInfo Response Builder

Usage

This extension point can be used if the user info response returned when accessing '/oauth2/userinfo' resource needs to be changed.
Implementations supporting both JSON and JWT response formats are available. By default JSON format supported implementation is configured in the identity.xml

Interfaceorg.wso2.carbon.identity.oauth.user.UserInfoResponseBuilder
Default Implementationorg.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoJSONResponseBuilder
Other Available Implementations

org.wso2.carbon.identity.oauth.endpoint.user.impl.UserInfoJWTResponse

Configuration
<UserInfoEndpointResponseBuilder>full qualified class name of the userinfo response builder</UserInfoEndpointResponseBuilder>