SAML SSO Error Handling in WSO2 Identity Server

This post explains on how to handle SAML SSO related errors in WSO2 Identity Server 5.2.0. In the SAML SSO flow, errors can be occurred due to several reasons. Some of them can be;

  • Signature verification failure of the SAML request or Response.
  • Mismatching ACS URLs in the request and the configuration.
  • Authentication failure in request path authentication.

The default behavior of the Identity Server is to redirect to the page with the error information. And the page will display the error content on the page.

Screen Shot 2016-07-13 at 3.10.07 AM

Note that the error information will be sent to the page as URL params. A typical response URL will look like the following;


Ideally, this error should be conveyed to the samlsso_notification.jsp. in the authentication endpoint. The following gist shows a modified samlsso_notification.jsp to POST the SAML response to ACS URL. However, this will only happen if the request URL consist with both SAML response and the ACS URL. Otherwise the page will display a generic error message. If needed, the page can be further modified to POST a static SAML response to a predefined ACS URL if those information cannot be extracted from the URL. But this will be not very straightforward when there are multiple ACS URLs since we won’t have enough information to determine from which service provider the login request initiated from.

In order to apply these changes to the product, either you can replace samlsso_notification.jsp in exploded authenticationendpoint.war directory located at [IS_HOME]/repository/deployment/server/webapps directory or you can checkout the source from [1], make the changes to samlsso_notification.jsp and build it. Once the source is built, you can drop the new authenticationendpoint.war file to the webapps directory. If there’s already a directory for authenticationendpoint, you’ll have to delete the directory as well.

Note: Even though this cannot be done to IS 5.1.0 out-of-the-box. By applying the fix mentioned in [2] you can achieve this in IS 5.1.0.

[1] –
[2] –


Security Token Persistence in WSO2 Identity Server 5.1.0

When we apply a security policy to the Security Token Service, a token store will also be specified. If we navigate to the registry path /_system/config/repository/axis2/service-groups/org.wso2.carbon.sts-5.0.7/services/wso2carbon-sts/policies/ and view the content of the applied policy, the token store details are included as follows


The token store class is picked from the following property in carbon.xml file.


However, the default DBTokenStore is an in-memory token store (regardless of what the name implies). Therefore, with time, the token store will retain a significant amount of JVM heap if a large number of users obtains security tokens. Also, the issued tokens will be invalid after a server restart.

If required, we can change the token store to a DB based one. For that change the TokenStoreClassName in carbon.xml as follows.


After changes, restart the server and re-apply the security policy to the Security Token Service. The tokens will be persisted in IDN_STS_STORE table.

Remote Profiling WSO2 Products with JProfiler

This post contains the steps to remote profile a WSO2 server using JProfiler

Setup Details:

  • WSO2 Identity Server 5.1.0 – Beta
  • JProfiler 9

You can download JProfiler from here.

Once JProfiler is downloaded and extracted, navigate to JProfiler, bin folder and run jpenable command.

Select the GUI Profiling mode and the program will request the profiling port. The default port will be 31757. If you don’t have a requirement to change the port, just press enter  so the profiling port will be the default port.

jprofiler9/bin$ ./jpenable
Connecting to org.wso2.carbon.bootstrap.Bootstrap [30483] ...
Please select the profiling mode:
GUI mode (attach with JProfiler GUI) [1, Enter]
Offline mode (use config file to set profiling settings) [2]
Please enter a profiling port

You can now use the JProfiler GUI to connect on port 31757

Then open JProfiler in your local machine, start a new session (Session > New Session or ⌘N in Mac) and attach the session to remove Identity Server instance using it’s IP and profiling port.


Hope this helps… 🙂

Setting AD FS 3.0 as a Federated Authenticator in WSO2 Identity Server

This post contains the steps required to configure AD FS 3.0 as a federated authenticator in WSO2 Identity server using SAML.

Note: This is will be supported out-of-the-box with Identity Server 5.1.0 M3 onwards. If you are to use this with Identity Server 5.0.0 (with SP 1) you’ll need to some modifications to the source. The details can be found at [1] & [2].


  • WSO2 Identity Server 5.1.0 M3 or above Identity Server Service Pack 2 (yet to be released)
  • ADFS 3.0

Adding IS as a Relying Party in ADFS

In ADFS Management UI expand Trust Relationship, right click on Relying Party Trust and select Add Relying Party Trust…

Screen Shot 1

Follow the wizard as shown below

Screen Shot 2

Screen Shot 3

Type a desired display name for the relying party and click Next.

Screen Shot 4

Select AD FS Profile and Click Next.

Screen Shot 5

We are not using an encryption certificate so click Next.

Screen Shot 6

Set the relying party SAML 2.0 SSO service url to the commonauth endpoint of IS. e.g: https://localhost:9443/commonauth

Screen Shot 7

Add the relying party trust identifier and click Next. The value you enter here should be entered in IS IdP settings as well. Setting up the IdP is explained in the next section.

Screen Shot 8

We won’t be configuring multi-factor authentication so click Next.

Screen Shot 9

Select Permit all users to access this relying party and click Next.

Screen Shot 10

Review the settings and click Next.

Screen Shot 11

Click Close to finish adding the relying party trust. Also let the wizard to open the Claim Rules dialog

Screen Shot 11

In the Edit Claim Rule dialog we will specify which claims to be sent to the relying party. In this example I’m sending the SAM-Account-Name LDAP attribute as a NameID claim.

First click Add Rule…

Screen Shot 12

Select Send LDAP Attributes as a claim and click Next.

Screen Shot 13

Set a Claim rule name and map SAM-Account-Name to E-Mail Address. Then click Finish.

Screen Shot 14

Click Add Rule… again to transform the email address claim to NameID claim. Select Transform an Incoming Claim and click Next.

Screen Shot 15

Set the Claim rule name. Select the incoming claim type as E-Mail Address and outgoing claim type and ID format as Name ID and Unspecified respectively. Then click Finish.

Screen Shot 16

Then apply and close the claim rules dialog.

Screen Shot 17

Before we wrap up things in AD FS side, there are few configuration changes needed to be done in Relying Party Trust properties. For that right click on the Relying Party Trust we just created and select Properties.

Screen Shot 17

Goto Signature tab and click Add.

Screen Shot 18

The certificate which should be added here depends on a couple of things. If the Service Provider in IS is under the super tenant domain. The public certificate of IS should be used. Else, the public certificate of the tenant domain should be selected. The public certificate of the tenant can be exported from the Key Management feature of the IS management console. In this post, the service provider is added in the super tenant domain and the default keystore has not been change. Therefore the default wso2carbon certificate is used. You can export the certificate from wso2carbon.jks which is located at /repository/resources/security/ directory.

Screen Shot 19

When importing the default certificate you will get the following dialog. Click Yes to proceed.

Screen Shot 20

Next move to Endpoint tab. Here we have to set the SAML logout endpoint. Click Add SAML…

Screen Shot 21

Select Endpoint Type as SAML Logout and the Binding as POST. Set the Trusted URL as https://<AD_FS_server>/adfs/ls  and the Response URL as the /commonauth endpoint of IS. Once it is done save the property settings of the RP.

Screen Shot 21

Next we will move on to configuring AD FS as an Identity Provider in IS. For the configurations we will have to add the Token signing certificate of AD FS. To export the token signing certificate of IS do as follows.

In AD FS management UI, click on Certificates under Service, right click on Token-signing certificate and select View Certificate.

Screen Shot 22

Goto Details tab and click Copy to File… Then follow the Certificate Export Wizard.

Screen Shot 23

Select Base-64 encoded X.509 (.cer) and click Next.

Screen Shot 23

Save the certificate to a desired location and Finish the wizard.

Screen Shot 24

Screen Shot 25

Screen Shot 26

We will move on to configuring IS next.

Adding AD FS as a Federated Authenticator in IS

Login to IS Management console and click Add under Identity Providers. Type a unique name for the IdP and add the Token-signing certificate of ADFS by clicking the Browse button.

Screen Shot 27

Next set the SAML Web SSO Configuration under Federated Authenticators.

  • Check Enable SAML2 Web SSO
  • Identity Provider Entity Id: This can be found in FederationMetadata.xml under entityID attribute. The FederationMetadata.xml can be accessed through https://<AD_FS_server>/FederationMetadata/2007-06/FederationMetadata.xml. The Entity ID is usually in the form http://<AD_FS_server>/adfs/services/trust
  • Service Provider Entity Id should be same as what’s given in AD FS RP trust identifier. eg:wso2-is
  • SSO URL should be in the form of http://<AD_FS_server>/adfs/ls
  • Check Enable Logout
  • Logout URL should be the same as SSO URL
  • Check Enable Logout Request Signing
  • Select HTTP Binding as POST

Once the details are entered click Register to save the IdP.

Screen Shot 28

[1] –
[2] –