Monday, May 28, 2012

Login to WSO2 Carbon servers via Shibboleth SAML2 IDP

In my previous post,  I went through step by step to configure the shibboleth as a SAML2 IDP.  Now lets try to use Shibboleth SAML2 IDP in a real word use case. In this blog post i am going to configure WSO2 Carbon product as a SSO service provider for  Shibboleth IDP. Any WSO2 Carbon server can act as a SAML2 SSO relying party components. 

This type of scenario actually useful when you want to login to management console of several WSO2 Carbon products that had been deployed as cluster; where users want to experience SSO. 

User experience would be as follows. 

1. User type WSO2 Carbon product management console url
2. User redirected to  the shibboleth login console 
3. User enter his user name and password associate with shibboleth IDP account   
4. User now has redirected to WSO2 Carbon product management console.

(But still i could not setup single logout with Shibboleth :( . Therefore you want to exit from the browser to logout from Shibboleth)

Here we want to understand one thing very carefully.  i.e User, who has an account in shibboleth IDP, must be also exist in the user store of the WSO2 Carbon server. Why?  For authentication, we do not want to duplicate the user accounts. Yes...!  Actually authentication would be successful at the WSO2 Carbon server without even a user store. But;  to login to the WSO2 Carbon management console, authentication is not enough, users are needed to authorize to access the management console.  Therefore after successful  authentication by using SSO,  WSO2 Carbon server performs an authorization check with respect to its own user store.  Therefore user must be in that user store also. (basically user Id and access control list).  But credentials do not want to be there. 

Therefore basically, you need to syn shibboleth IDP with WSO2 Carbon user store. For this we can have two options. 

1. Use provisioning mechanism such as SCIM (SCIM would be supported by WSO2Carbon server 4.0.0 version) 
2. Share same user store for shibboleth IDP and WSO2 Carbon servers. Most of the cases,  shibboleth IDP is backed by LDAP or AD. Therefore we can easily configure WSO2 Carbon servers to connect to that LDAP or AD.   But authentication check would be always happened at the shibboleth IDP. 

Now lets go with configurations. 

First configure at shibboleth IDP side,

Step 1.  Configure new relying party for carbon servers under the "RelyingPartyGroup"  in relying-party.xml which can be found at IPD_HOME/conf directory.   Sample configuration would be as follows 

<rp:RelyingParty id="carbonServer"
        defaultSigningCredentialRef="IdPCredential" defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport">
    <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" signResponses="always" signAssertions="never" 
                                 encryptAssertions="never" encryptNameIds="never"/>

Here i have configured only to sign the SAML2 response.

Step 2. Configure SAML2 meta data configuration by using a new meta data config file at IPD_HOME/metadata directory.  In this directory, I created a new file called carbon.xml and configure followings.

<EntityDescriptor entityID="carbonServer" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://localhost:9443/acs" />

Please make sure  NameIDFormat, Binding in ACS and Location of ACS are configured according to your own configurations

Step 3. Configure new meta data configuration file under the "RelyingPartyGroup"  in relying-party.xml which can be found at IPD_HOME/conf directory.   Sample configuratio cn would be as follows 
Here we have pointed to the new meta data config file.

<MetadataProvider id="carbonMD" xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
    metadataFile="/home/asela/shibboleth/metadata/carbon.xml" maintainExpiredMetadata="true" />

Now lets configure Service provider side,  WSO2 Carbon server.

WSO2 Carbon server can be configured with different authenticators.   AuthenticationAdmin (which uses user name and password) is the default Carbon Server Authenticator. Therefore we need to change those configurations and enable Shibboleth related SAML2 SSO authenticator.  Actually there is existing SAML2 SSO authenticator that can be found at this SVN location. But it seems to be that default SAML2 SSO authenticator would not work with Shibboleth out of the box. Therefore you need to write a new authenticator for shibboleth. It would be really easy, because we only need to do small modifications to the existing SAML2 SSO authenticator source code.  Therefore I did that simple modification.  You can find the modified source from here.  And the patched jar files from here.  

Lets see how we can do this.  please note here i am using Carbon 3.2.3 based servers.

Step 1.  Install following patched SAML SSO authenticator jars  with WSO2 Carbon server by copying them in to  <CARBON_HOME>/repository/components/dropins


Step 2.  Configure authenticators.xml file which can be found at <CARBON_HOME>/repository/conf/advanced  directory. Sample configuration would be as follows

    <Authenticator name="SAML2SSOAuthenticator">
            <Parameter name="LoginPage">/carbon/admin/login.jsp</Parameter>
            <Parameter name="ServiceProviderID">carbonServer</Parameter>
            <Parameter name="IdentityProviderSSOServiceURL">https://localhost:8443/idp/profile/SAML2/Redirect/SSO</Parameter>

Here please note following two parameters must be according your configurations.

ServiceProviderID -> This must be same value that you have configured as RelyingParty Id.
IdentityProviderSSOServiceURL  -->  This must be the SSO redirect url of shibboleth IDP

Step 3. Start the server and try to login to management console,  you would probably redirected to  shibboleth  IDP login page..   

Configure Shibboleth as SAML2 IDP

Shibboleth  is one of a most popular SAML2 IDP that is widely used.  I tried to configure shibboleth  as SAML2 IDP. In this post i am going to share these steps with you. I hope that would be useful for you also.  My Operating System  was ubunutu 10.04

Step1. Download  latest version (v2.3.6) of  shibboleth IDP from here 

Step2. Extract in to your file system. 

Step3. Go to root directory and run install script.  This would install shibboleth in to given location in your file system Lets call it as IDP_HOME. Also this installation would create a key store which can be found at  IDP_HOME/credentials directory  and war file which can be found at  IDP_HOME/war directory.

First let configure a user store with shibboleth.  We can use LDAP based user store for this. Here i am using the ApacheDS LDAP user store.  You can find simple steps to create an ApacheDS LDAP server from here.

Step4. Open login.config file which can be found at IDP_HOME/conf directory and configure your LDAP user store.  following is my sample configurations. 

ShibUserPassAuth {

edu.vt.middleware.ldap.jaas.LdapLoginModule required


Step5.  Enable username/password login handler from handler.xml file which can be found at IDP_HOME/conf directory. 

    <ph:LoginHandler xsi:type="ph:UsernamePassword" 

Step6. Configure logging level from logging.xml  file can be found at IDP_HOME/conf directory.  All the logs files would be saved at  IDP_HOME/logs.  This would probably help you to trouble shooting the issues.

Now let deploy idp.war file in a web application server.  Here i am using apache tomcat for this.  Please use tomcat 6.X.X as shibboleth is not tested with tomcat 7.X.X

Step7. Copy  IDP_HOME/lib/endorsed  directory in to tomcat root directory. 

Step8.  Enable HTTPS in tomcat.  Locate the server.xml at TOMCAT_HOME/conf directory and configure HTTPS connector.  Sample configuration would be as follows. 

<Connector port="8443"
           keystorePass="changeit" /> 

Step9. Copy idp.war  file in to  TOMCAT_HOME/webapp directory.

Step10. Start tomcat server  by running  catalina script. 

Step11. Check status of the server by using   https://localhost:8443/idp/status

Wednesday, May 2, 2012

Claim management with WSO2 Identity Server

What is a Claim?

A claim is a piece of information (or statement) about a subject (or user). It can be a anything that subject owned by or associated with it, such as name, group, preferences and etc. Claim provides a single and general notion to define the identity information related the subject.

Claims-based identity is a common way for any applications to acquire those identity information. It provides a consistent approach for all applications by hiding the lower level implementation.

Also Claims are used in identity propagation, by packaging the claims into one or more tokens (such as SAML). And those are then issued by an issuer; commonly known as a security token service (STS).

Claim Management

The Claim Management component of the WSO2 Identity Server enables you to define set of claims for users. It maps a set of attributes from the underlying user store to a set of defined claims. 

Each claim can be uniquely identified by the Claim Uri. Claim Uris are independent from the user store and each claim uri can be mapped into the any desired attribute in the user store; which are also associated with user profile. The underlying user store can be either JDBC , LDAP or AD that can be configured using user-mgt.xml file. 

Claim Dialect

A set of claims are identified as a dialect. Different dialects represents the same piece of information with different claim URIs.

Following dialects are defined by-default with WSO2 Claim Management Component. Those are populated when the server is started at first time; by reading the claim-mgt.xml file which can be found at <IS_HOME>

  • : Default dialect for WSO2 Carbon (Claim set of this dialect is used for default user profile)
  • : Default dialect for Information Cards 
  • : Default dialect for OpenID Attribute EXchange 
  • : Default dialect for OpenID Simple Registration

Defining Claim Dialect

You can define a new Claim Dialect by clicking on the link 'Add New Claim Dialect' in Claim management UI.
  • Dialect Uri : URI which uniquely identifies the Dialect. Eg :-

Each dialect should have at least one claim. Therefore you need to define the claim configuration as defined in next heading 

Defining Claim

You can extend a defined dialect by adding new claim mappings. Click 'Add New Claim Mapping' link to add a new claim mapping.

  • Display Name : Name of the claim displayed on the UI (displayed name in the user profile)
  • Description : Describe the functionality of the claim
  • Claim Uri : URI defined under the dialect, specific to the claim (Unique identifier for claim)
  • Mapped Attribute : Corresponding attribute name from the underlying user store
  • Regular Expression : Regular expression to validate inputs (which are entered, when configuring user profiles)
  • Display Order : Display order of the claim among all the other claims defined under the same dialect
  • Supported by Default : If unchecked won’t be prompted in user profile and in user self registration
  • Required : Required for claims for user profile and user self registration


Lets assume that there is an attribute called “policyId” in the under line user store (say openldap). And Lets make it as a required claim value in the user’s identity using claim management. 

Step 1 : Login to Identity Server management console as admin user

Step 2. Go to Configure -> Claim Management UI

Step 3. Locate WSO2 Carbon claim dialect (

Step 4. Create new claim under the 
WSO2 Carbon claim dialect and map it for for the policyId attribute

Lets define claim as follows;

Claim Uri as --> (unique id to identify the claim)

Display Name → Policy Id (Displayed name in user profile UI and Claim management UI)

Description -- > Policy Id of the User (Description about claim)

Mapped Attribute → policyId (Attribute id of the user store)

Regular Expression → ^[0-9] (regular expression to configure only the numerical values)

Display Order → 3 (Display order in user profile)

Supported by Default → true (This claim is in user profile and
user self registration by default)

Required → true
(This claim is a required claim in user profile and user self registration)

Step 5. Go to My Identity -> My Profiles and View default profile

Step 6. Policy Id can be seen as required attribute where you can configure only numerical values [0-9] 

Step7. Log out from the admin console and go to self registration page. Identity -> Sign-up -> User name/password 

Step 8. Policy Id can be seen as required attribute when user registration and you can register with only numerical values