Monday, March 14, 2016

User Store Count with WSO2 Identity Server 5.2.0

This post is to provide details on one of the new functionalities introduced with WSO2 Identity Server 5.2.0, to be released soon. This feature comes with a service to count the number of users based on user names patterns and claims and also to count the number of roles matching a role name pattern in user store. By default this supports JDBC user store implementations only and provides freedom to extend the functionality to LDAP user stores or any other type as well.

How to Use?

A new property is introduced in user store manager configuration named 'CountRetrieverClass', where we can configure the class name that carries the count implementation for particular user store domain.

Using Service

The functionality is exposed via a service named 'UserStoreCountService' which provides relevant operations as below.

Separate operations are provided to get the counts of a particular user store or the whole user store chain for following functionalities.
  • Count users matching a filter for user name
  • Count roles matching a filter for role name
  • Count users matching a filter for a claim value
  • Count users matching filters for a set of claim values (eg: count of users whose email address ends with '' and mobile number starts with '033')


In order to extend the functionality, this interface '' should be implemented by the class, packaged into an OSGI bundle and dropped into the dropins folder within WSO2 Identity Server.

Thursday, February 25, 2016

Account Deactivation with WSO2 Identity Server - 5.2.0

This is about a new feature addition that can be expected to be out with WSO2 Identity Server 5.2.0 version, which has been added to the current master branch for WSO2 IS at

This feature is to cater for account disability requirements in addition to account locking. Account disabling function is provided through a user claim as similar to account locking functionality. While account locking is a temporarily blocking of user login due to a defined policy like consecutive unsuccessful login, account disabling will cater for disabling user account which is much more long term.

How to try?
  • Enable 'org.wso2.carbon.identity.mgt.IdentityMgtEventListener' in <IS_HOME>/repository/conf/identity/identity.xml file under Event Listeners.
  <EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener"
                       orderId="50" enable="true"/>
  • in <IS_HOME>/repository/conf/identity/ file configure below properties.

After the configurations are done, restart the server to have them effective.
Under claim manaement of WSO2 Identity Server, edit the claim ""to be supported by default. How to do this is described at

Now the required configurations are done. We can disable, enable user accounts through user profile.

Monday, January 04, 2016

OAuth - Extension Points Part 2 - WSO2 Identity Server

OAuth2 is widely used in the enterprise today for authorization aspects of APIs. This is the second post on the extension points available in WSO2 Identity Server after WSO2 Identity Server - Extension Points - Part 1 - SAML

All the implementation using following extension point needs to be configured at <IS_HOME>/repository/conf/identity/identity.xml file under the element OAuth.

  • Custom OAuth grant handler


When we need to support an OAuth flow that is different from standard grant types. Validates the grant, scopes, and access delegation.



  • Client Auth Handler


When the client credential authentication needs to be customized. By default we validate the client id and secret.



  • OAuth Callback Handler

An extension point 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. There are registered through the identity.xml. 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 will be chosen. After handling the callback, it can set whether the given callback is authorized or not.



Abstract Class / Default Implementation:


  • Token Persistence Processor

Implementations are used to process keys and secrets just before storing them in the database. E.g. to encrypt tokens before storing them in the database. Implementations of this interface can be configured through the identity.xml.



Abstract Class / Default Implementation:

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

  • User Info Access Token Validator

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



Default Implementation:


  • User Info Claim Retriever

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



Default Implementation:


  • User Info Request Validator

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



Default Implementation:


  • User Info Response Builder

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



Default Implementations:


  • Authorization Context Token Generator

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


Default Implementation:


  • Claims Retriever

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 under identity.xml -> OAuth -> TokenGeneration -> ClaimsRetrieverImplClass

Any deviation can be done using this extension.


  • Response Type Handler

This is intended to validate access delegation and oauth scope validation. Then issue codes or tokens. In this flow needs to be customized this extension can be used.


  • OAuth2 Token Validator

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



Tuesday, December 01, 2015

WSO2 Identity Server - Extension Points - Part 1 - SAML

This is the first post of a series of post to come, to serve as a catalog of extension points available within WSO2 Identity Server as of IS 5.1.0 version which is to be released soon. Most of them are available in 5.0.0 version as well. We have quite a lot of flexibility provided for the users to shape Identity Server to serve exactly what they require via these extension points.

There are 2 types of extensions available in WSO2 Identity Server as of now. Most of these require a restart of the server in order to be effective, but can be configured dynamically without a restart of the server. Few of the extensions like UI theming can be made without a server restart.
  • Drop the extension developed as an OSGI bundle, followed by a server restart,  configure it dynamically
      • eg: custom user store managers
  • Drop the extension developed as a Java component, configure in a configuration file, then restart the server. Configure it dynamically via the UI.
      • eg: custom authenticators

Files Used for Configurations

  1. The configuration files for these extensions are located at <IS_HOME>/repository/conf folder. 
  2. Most of the configurations specific to identity server resides identity/identity.xml within this folder. 
  3. Configurations relevant to federation scenarios(authentication framework) resides at identity/application-authentication.xml file. 
  4. Identity management related configurations resides at identity/ file. 
  5. Entitlement(XACML) related configurations resides at identity/ file.
    Apart from above we have multiple listeners and UI modifications allowed for branding purposes.
Note: Though the extension points are available to cater for variety of enterprise needs, this introduces a maintenance overhead in long term. If these are valid generic scenarios we will be merging these to product itself, otherwise these extensions needs to be maintained at major upgrades if there is any API change or improvements done at interfaces.

First our attention is for SAML based scenario as that is a widely used standard on Single Sign On.

Please find a list of available extension points related to this scenario below.

All the implementation using following extension point needs to be configured at <IS_HOME>/repository/conf/identity/identity.xml file under the element ‘SSOService’.

  1. Custom SSO Signer


When we want to change the way we sign/validate the SAML Response or Assertion. If this is just changing the algorithms default UI configurations are available without going for this extension.



Default Implementation:

  1. Custom SSO encryption


When we want to change the way we encrypt the SAML assertion in local


Default Implementation:

  1. SAMLAssertionBuilder


This extension point can control how the SAML assertion it built. Intend use of the extension point is put the given inputs in the SAML assertion format as preferred. This extension point gives full control over what is there in SAML assertion.  


Default Implementation:

  1. SAML2HTTPRedirectSignatureValidator


Can be used to differentiate(deflating, encoding etc.) on how the signature is validated at SAML HTTP redirect binding.



Default Implementation:


  1. ResponseBuilder


This extension point provides the full control over the SAML Responses built to sent over to replyingparties


Default Implementation:

 If there are any other use cases or samples you have found useful around WSO2 Identity Server SAML implementation, you are most welcome to add them here, for the benefit of all. Thanks!

The second post is available at OAuth - Extension Points Part 2 - WSO2 Identity Server on the extension points in WSO2 Identity Server related to OAuth2.0.

Sunday, September 21, 2014

Leveraging federation capabilities of Identity Server for API gateway - Configuration Details

With this post I am to share the steps of a popular solution using WSO2 Identity Server and WSO2 API Manager. Following diagram will give an initial insight on this solution.


1.  Webapp that requires single sign on(SSO) facility with some other applications. 
                - To achieve this we are using WSO2 Identity Server(IS) as the Identity Provider(IDP). 

2.  Webapp needs to consume some APIs secured with OAuth tokens. 
                - To expose the APIs secured with OAuth tokens we are using WSO2 API Manager(AM) here.
                - Since we already have the SAML Response received at SSO step, SAML2 Bearer grant type is ideal to use at this scenario to request an OAuth token to access the required APIs.
                - Allowing AM to properly issue an OAuth token in this scenario, we add IS as a trusted IDP in AM.

3.  Webapp requires to allow users registered in another IDP like Facebook or Google to be able to login with SSO functionality. 
                - With minimum configurations to internal IS and external IDP side, we need to achieve this.
Rest of this post will deal with how we can configure the above, without sharing any databases underneath. Will setup this in multi-tenancy mode, to make it a more general scenario. Another instance of WSO2 Identity Server will be used in the place of external IDP. This can be replaced with Facebook, Google etc. according the requirement.


WSO2 Identity Server -5.0.0 -
WSO2 API Manager 1.7.0 -
                             The compiled webapp ready to deploy in a servelet container, can be found here.
As we are to run several instances of WSO2 servers we need to configure port offsets, if all are configured in one machine. Following are the port offsets and ports I am to use. I will be using two tenants in the two Identity servers and API manager will be run of super tenant mode.

1. WSO2 Identity Server -5.0.0 - Internal IDP - Offset 0 - Port 9443 
                 Tenant -
2. WSO2 Identity Server -5.0.0 - Internal IDP - Offset 1 - Port 9444 
                 Tenant -
3. WSO2 API Manager 1.7.0 - API Gateway - Offset 2 - Port 9445
                 Tenant - carbon.super

Webapp Configurations 

If you download the webapp from the above link, the keystore configurations are already done. You will only need to import the public certificate of the tenant in internal IDP( to the keystore of webapp 'travelocity.jks'. 
Please note the following configurations done in file found inside webapp at '/'.


#A unique identifier for this SAML 2.0 Service Provider application

#The URL of the SAML 2.0 Identity Provider

#Password of the KeyStore for SAML and OpenID

#Alias of the IdP's public certificate

#Alias of the SP's private key 

#Private key password to retrieve the private key used to sign 
#AuthnRequest and LogoutRequest messages

#OAuth2 token endpoint URL

#OAuth2 Client ID

#OAuth2 Client Secret

1. SSO Setup with Internal IDP

  • Login as tenant admin - <admin>
  • Export the public certificate of the private key used at webapp side to sign the SAML Authentication Request. Following command can be used to export it.
keytool -export -alias travelocity -file travelocity -keystore <path to travelocity.jks(which ever keystore used at webapp side)>
  • Import the above exported public certificate to the tenant key store of the internal IDP, identity server as below.

  • After the import it will listed as below.

  • Create a new Service Provider for Travelocity webapp as following.
  • Then we needs to configure it as below.    
- By enabling SaaS application, we are removing the tenant boundary for this service provider.
- Enable response and assertion signing according to your requirement.
- Enable signature verification for SAML Authentication Request

The configurations are mostly done to get the SSO scenario work with the webapp. We need to export the tenant public certificate to be imported to the trust store at webapp side. This is in order to verify the SAML Response/Assertion signed signature at the webapp side. We can export the certificate as below from the UI, using public key link.


The exported key needs to be imported to webapp truststore(in this case travelocity.jks we located inside the webapp).

keytool -import -alias <The given alias name. Here> -file <path to downloaded public certificate> -keystore <path to trust store of webapp. Here the travelocity.jks file>

Now if you try to login to travelocity web app as a tenant user, it should succeed.

2. External federation

Following configuration will demonstrate how to configure an external identity provider in Identity Server. Here we will use another instance of identity server as the external IDP. The scenario will be extended from the previous scenario. 

At internal federation, we had 'Travelocity' webapp registered as a Service Provider in the IDP which decided the authenticity of user. Now we will federate the decision on the authenticity of the user to an external IDP. For the demonstration purposes I am using a tenant(named in the external IDP(

Configuring another IS instance to act as an external IDP (

  • Create a tenant named ‘’ and login with this tenant.
  • First we need to import the public certificate of the internal IS into tenant key store, which is paired with the private key used to sign the SAML Request. This time it is 'wso2carbon'.
  • Configure the internal IS as a service provider here. This is because now the SAML request is to be sent to this IS by the internal IS, we configured before.
  • Note that ‘Assertion Consumer URL’ is pointed to ‘https://localhost:9443/commonauth’ of the internal IS. Also note the certificate alias we have selected to use at SAML Request signature validation. This is the one that we imported here.

Configure Internal IS to federate SSO requests from Travelocity webapp to the external IDP

In the internal IS, we need to configure it to make use of the external IDP we just configured.
  • Create a Identity Provider as below. 
  • Upload the public certificate we can download from the external IDP, tenant keystore. This is to validate the signatures of SAML Response and Assertions that will be sent to this internal IS from the external IS.

We have to make some additional changes in the service provider configuration for Travelocity webapp as well. 
  • In the drop down list of federated authenticators select the identity provider we just configured.

There is one more addition we have to do as following to meet the requirement of audience restriction validation in SAML SSO scenario. This is not a requirement for federation, but for API access. The value we give here for audience is the OAuth token endpoint, which we will consume to exchange the SAML token for an OAuth token.

Now we are in a position to test the external federation scenario with Travelocity webapp sample. After hosting it in a tomcat server, hit the URL, ‘http://localhost:8080/’, which will take us to a page as below. Click on the link to login with SAML.

This will take us to following screen. Note the page is from our external IDP (, where we can enter credentials of a user in this IDP to get successfully authenticated. If our external authenticator was Google this will be a page from Google, submitted to enter the credentials.

After successful authentication, following screen will be shown.

Now the external federated SAML scenario is completed.

3. API Access leveraging the federation

To achieve this we need following configurations present at Webapp side.
  • Register an application in API-M store, subscribe to some APIs, provide the generated client id and client secret values in file of the sample webapp.
  • Point SAML.OAuth2TokenEndpoint=https://localhost:9445/oauth2/token to OAuthtoken endpoint of API-M.
  • Import the public certificate of internal IS, to the  keystore used by webapp. The given alias value should be provided at ‘’ in file.

IDP Configuration at API-M

  • Configure ‘host name’ and ‘mgt host name’ in APIM_HOME/repository/conf/carbon.xml 
  • Login as super admin and add an identity provider as following.

  • Following fields needs to be filled. Note that we have imported the public certificate of the internal IS here, so that we can validate it’s SAML token.
  • API-M is not aware of the federation happening at the internal IS node.

  • When configuring the federated authenticator, we should note that Identity Provider entity id should be as same as the issuer of the SAML Response coming to API-M, to exchange for an OAuth token. SSO URL, is the redirect URL for internal IS.

  • Once these configurations are done, we can test the end-to-end scenario. Now from the page we left at ‘Travelocity’ webapp, if we click on the link ‘Request OAuth2 Access Token’ following page will appear. It is showing the details of the OAuth token, it received in exchange to the provided SAML token.

Now we can use this access token at webapp side to consume any APIs we got subscribed to.

Hope this helps. We can expand and customize this scenario in several ways according to requirements, with options provided with federation, provisioning and extension points. Will discuss those in a latter post.