Page Comparison

This topic includes a list of all the WSO2 Identity Server extension points related to OAuth . All implementations using the following extension points must be configured 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 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.

Table of Contents

maxLevel	3
minLevel	3

...


exclude	Implementing an OAuth Extension

Anchor
OAuth Grant Handler
OAuth Grant Handler
OAuth Grant Handler

Usage	This 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.

SampleSee Writing a Custom OAuth 2.0 Grant Type for a sample implementation of this extension point.UsageScope handlers are executed during the scope validation step when issuing an access token. Multiple scope handlers can be registered using a sample configuration given below.

Interface	org.wso2.carbon.identity.oauth2.token.handlers.grant.AuthorizationGrantHandler

Custom Scope Handler

Abstract Class

org.wso2.carbon.identity.oauth2.token.handlers.grant.AbstractAuthorizationGrantHandler

Configuration

Code Block

language	xml

<OAuth>

<SupportedGrantTypes>

.

	...
	<SupportedGrantType>

 	<GrantTypeName>grant type identifier </GrantTypeName>

<ScopeHandler class="org.fully.qualified.class.name.CustomScopeHandler"> <Property name="foo">foo-value</Property> </ScopeHandler> </ScopeHandlers>

	<GrantTypeHandlerImplClass>full qualified class name of grant handler</GrantTypeHandlerImplClass>
	</SupportedGrantType>
</SupportedGrantTypes>

Sample

See 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 Class

org.wso2.carbon.identity.oauth2.

validators.OAuth2ScopeHandler

Extended Scope Validator

UsageThese are executed during the token validation stepwhen validating an access token. Multiple scope validators can be registered using a sample configuration given below.

token.handlers.grant.AbstractValidator

Configuration

Code Block

language	xml

<OAuth>

<SupportedGrantTypes>

.

	...
	<SupportedGrantType>

 	<GrantTypeName>grant type identifier </GrantTypeName>

	<GrantTypeHandlerImplClass>full qualified class name of grant handler</GrantTypeHandlerImplClass>
    	<GrantTypeValidatorImplClass>full qualified

<Property

class name

="foo">foo-value</Property> </ScopeValidators> </ScopeValidators>Abstract Class

org.wso2.carbon.identity.oauth2.validators.OAuth2ScopeValidator

...

 of grant validator</GrantTypeValidatorImplClass>
	</SupportedGrantType>
</SupportedGrantTypes>

Client Authentication Handler

Usage

In the WSO2 Identity Server, you can customize the token generating logic by configuring IdentityOAuthTokenGenerator under OAuth in the <IS_HOME>/repository/conf/identity/identity.xml directory.

The following is the default implementation:

Usage	This extension point can be used when the client credential authentication needs to be customized when issuing tokens. By default the Identity Server validate the client id and secret.
Interface	org.wso2.carbon.identity.oauth2.token.handlers.clientauth.ClientAuthenticationHandler

IdentityOAuthTokenGenerator

Abstract Class

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

Default Implementation

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

Configuration

Code Block

language	xml

<ClientAuthHandlers>
	...
	<ClientAuthHandler class="full qualified class name of client authentication handler">
	</ClientAuthHandler>
</ClientAuthHandlers>

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.
Interface	org.wso2.carbon.identity.oauth2.token.OauthTokenIssuer
Default Implementation	org.wso2.carbon.identity.oauth2.token.OauthTokenIssuerImpl

Interface

Other Available Implementations	org.wso2.carbon.identity.oauth2.token.

OauthTokenIssuer

...

JWTTokenIssuer

Configuration

Code Block

language	xml

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

OAuth Callback Handler

Usage

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

Interface

org.wso2.carbon.identity.oauth.callback.OAuthCallbackHandler

Abstract

class/default implementation

Class	org.wso2.carbon.identity.oauth.callback.AbstractOAuthCallbackHandler
Default Implementation	org.wso2.carbon.identity.oauth.callback.DefaultCallbackHandler

TokenPersistenceProcessor

UsageImplementations are

Configuration

Code Block

language	xml

<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

, e.g.,

. 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. Implementations of this interface can be configured through the identity.xml file.Its recommended to configure this in initial configuration. If not already persisted data has to migrate in to new format

database and to decrypt when retrieving back from database.

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

Interface

org.wso2.carbon.identity.oauth.tokenprocessor.TokenPersistenceProcessor

Abstract class/default implementation

Default Implementation

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

EncryptionDecryptionPersistenceProcessor

PlainTextPersistenceProcessor

Other Available Implementations

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

PlainTextPersistenceProcessor

UserInfoAccessTokenValidator

UsageValidates the access token and returns the token info. Default behavior is validating the access token with WSO2 IS token validation OSGI service(Scope is also checked to have openid scope). If this needs to be modified this can be used

EncryptionDecryptionPersistenceProcessor

Configuration

Code Block

language	xml

<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.
Interface	org.wso2.carbon.identity.

oauth

oauth2.

user

validators.

UserInfoAccessTokenValidator

OAuth2TokenValidator
Default implementation	org.wso2.carbon.identity.

oauth

oauth2.

endpoint.user.impl.UserInfoISAccessTokenValidator

UserInfoClaimRetriever

UsageDefault behavior is creating claim URI and claim value pairs according to the claim mappings received. Any modifications to this default behavior can be done here

validators.DefaultOAuth2TokenValidator

Configuration

Code Block

language	xml

<TokenValidators>
	<TokenValidator type="token type" class="full qualified class name of the oauth2 token validator"/>
</TokenValidators>

Anchor
AuthorizationContext Token Generator
AuthorizationContext Token Generator
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.

Interface

org.wso2.carbon.identity.

oauth

oauth2.

user

authcontext.

UserInfoClaimRetriever

Default
AuthorizationContextTokenGenerator

implementation

Implementation	org.wso2.carbon.identity

.oauth.endpoint.user.impl.UserInfoUserStoreClaimRetriever

UserInfoRequestValidator

UsageThe default behavior is validating the schema and authorization header according to the specification. Any further additional validations or modification to this validation on user information request can be done using this extension

.oauth2.authcontext.JWTTokenGenerator

Configuration

Code Block

language	xml

<AuthorizationContextTokenGeneration>
	...
   	<TokenGeneratorImplClass>full qualified class name of the authorization context token generator</TokenGeneratorImplClass>
    ...
</AuthorizationContextTokenGeneration>

Info
For more infomation on above configuration refer here.

Anchor
ClaimsRetriever
ClaimsRetriever
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.
Interface	org.wso2.carbon.identity.

oauth

oauth2.

user

authcontext.

UserInfoRequestValidator

Default
ClaimsRetriever

implementation

Implementation	org.wso2.carbon.identity

.oauth.endpoint.user.impl.UserInforRequestDefaultValidator

UserInfoResponseBuilder

Usage

Creates the UserInfoResponse. By default the response can be in JSON or JWT format. When a different format is required, this extension can be used to support it.

If you need to add custom claims into the /userinfo endpoint response, you can implement a custom response builder by implementing the UserInfoResponseBuilder interface.

Interface

.oauth2.authcontext.DefaultClaimsRetriever

Configuration

Code Block

language	xml

<AuthorizationContextTokenGeneration>
	...
    <ClaimsRetrieverImplClass>full qualified class name of the claims retriever</ClaimsRetrieverImplClass>
    ...
</AuthorizationContextTokenGeneration>

Info
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.
Interface	org.wso2.carbon.identity.oauth2.authz.handlers.ResponseTypeHandler
Abstract Class	org.wso2.carbon.identity.

oauth

oauth2.authz.

user

handlers.

UserInfoResponseBuilder

AbstractResponseTypeHandler

Default implementation

Available Implementations	org.wso2.carbon.identity.

oauth

oauth2.

endpoint

authz.

user

handlers.

impl.UserInfoJSONResponseBuilder

CodeResponseTypeHandler
org.wso2.carbon.identity.

oauth.endpoint.user.impl.UserInfoJWTResponse

AuthorizationContextTokenGenerator

Usage

Generates the token relevant to the authorization context. By default JWT token generation is supported with the following properties encoded to each authenticated API request.

subscriber, applicationName, apiContext, version, tier, and endUserName
Additional properties can be encoded by engaging the below extension
The JWT header and body are base64 encoded separately and concatenated with a dot
Finally the token is signed using SHA256 with RSA algorithm.

Any deviations can be made via this extension and configured in the <IS_HOME>/repository/conf/identity/identity.xml file

oauth2.authz.handlers.TokenResponseTypeHandler

Configuration

Code Block

language	xml

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

Interface

org.wso2.carbon.identity.oauth.user.UserInfoAccessTokenValidator

Default implementation

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

Configuration

Code Block

language	xml

<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.
Interface	org.wso2.carbon.identity.

oauth2

oauth.

authcontext

user.

AuthorizationContextTokenGeneratorUsage

The default implementation class of this ClaimsRetriever reads user claim values from the default Carbon user store. The user claims are encoded to the token in the natural order of the claimURIs by the previous token generator. To engage this class, its fully qualified class name should be mentioned in the <IS_HOME>/repository/conf/identity/identity.xml file. This is found under the OAuth tag and nested inside ClaimsRetrieverImplClass which is under TokenGeneration.

Any deviation can be done using this extension.

UserInfoClaimRetriever

ClaimsRetriever

Default implementation

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

Configuration

Code Block

language	xml

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

Interface

org.wso2.carbon.identity

.oauth2

.

authcontext.AuthorizationContextTokenGenerator

ResponseTypeHandler

UsageThis is intended to validate access delegation and also conduct

oauth

scope validation. You can issue codes or tokens. If this flow needs to be customized, this extension can be used.Interface

.user.UserInfoRequestValidator
Default implementation	org.wso2.carbon.identity.oauth.

oauth2

endpoint.

authz

user.

handlers.ResponseTypeHandler

...

impl.UserInforRequestDefaultValidator

Configuration

Code Block

language	xml

<UserInfoEndpointRequestValidator>full qualified class name of the userinfo endpoint request validator</UserInfoEndpointRequestValidator>

UserInfo Response Builder

Usage	This

is useful when a token is sent back for validation purposes to validate on scopes, check the validity of access token and access delegation.

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
Interface	org.wso2.carbon.identity.

oauth2

oauth.

validators

user.

OAuth2TokenValidator

OAuthScopeValidator

UsageScope validation custom implementations can be plugged in by extending this class and providing the validation logic.AbstractClass

UserInfoResponseBuilder
Default Implementation	org.wso2.carbon.identity.oauth.

oauth2

endpoint.

validators.OAuth2ScopeValidator

OIDCScopeValidator

UsageScope validation custom implementations can be plugged in by extending this class and providing the validation logic.AbstractClass

user.impl.UserInfoJSONResponseBuilder
Other Available Implementations	org.wso2.carbon.identity.

oauth2.validators.OIDCScopeValidator

oauth.endpoint.user.impl.UserInfoJWTResponse

Configuration

Code Block

language	xml

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

Versions Compared

Old Version 13

New Version 14

Key

Implementing an OAuth Extension

Anchor
OAuth Grant Handler
OAuth Grant Handler
OAuth Grant Handler

Custom Scope Handler

OAuth Grant Validator

Extended Scope Validator

Client Authentication Handler

IdentityOAuthTokenGenerator

OAuth Token Generator

TokenPersistenceProcessor

Token Persistence Processor

UserInfoAccessTokenValidator

OAuth2 Token Validator

UserInfoClaimRetriever

Anchor
AuthorizationContext Token Generator
AuthorizationContext Token Generator
AuthorizationContext Token Generator

UserInfoRequestValidator

Anchor
ClaimsRetriever
ClaimsRetriever
Claims Retriever

UserInfoResponseBuilder

Response Type Handler

AuthorizationContextTokenGenerator

UserInfo Access Token Validator

UserInfo Claim Retriever

ClaimsRetriever

UserInfo Request Validator

ResponseTypeHandler

UserInfo Response Builder

OAuthScopeValidator

OIDCScopeValidator

Page Comparison

Versions Compared

Old Version 13

New Version 14

Key

Implementing an OAuth Extension

AnchorOAuth Grant HandlerOAuth Grant HandlerOAuth Grant Handler

Custom Scope Handler

OAuth Grant Validator

Extended Scope Validator

Client Authentication Handler

IdentityOAuthTokenGenerator

OAuth Token Generator

TokenPersistenceProcessor

Token Persistence Processor

UserInfoAccessTokenValidator

OAuth2 Token Validator

UserInfoClaimRetriever

AnchorAuthorizationContext Token GeneratorAuthorizationContext Token GeneratorAuthorizationContext Token Generator

UserInfoRequestValidator

AnchorClaimsRetrieverClaimsRetrieverClaims Retriever

UserInfoResponseBuilder

Response Type Handler

AuthorizationContextTokenGenerator

UserInfo Access Token Validator

UserInfo Claim Retriever

ClaimsRetriever

UserInfo Request Validator

ResponseTypeHandler

UserInfo Response Builder

OAuthScopeValidator

OIDCScopeValidator

Anchor
OAuth Grant Handler
OAuth Grant Handler
OAuth Grant Handler

Anchor
AuthorizationContext Token Generator
AuthorizationContext Token Generator
AuthorizationContext Token Generator

Anchor
ClaimsRetriever
ClaimsRetriever
Claims Retriever