Towards a viable and secure health information system - Part 5

This is the fifth and the final of the series of blog posts that I have been writting on the $sbject, inspired by the paper[1].

Let me include the following diagram which illustrates the overall picture on the security requirements of a health information system.

In my previous four posts in this series, I have discussed about Identity Management/Authentication,, Authorization, Auditing and Cryptographic Operations related to the security of health information systems. In this post, I am going to write about another three aspects which are discussed in the paper[1]: de-identification of EMRs for research purposes, user interaction and dispute resolution and security metrics.

5. De-identification

While the EMRs are very useful in medical research as statistics, it should be guaranteed that the records are properly de-identified before disclosing them for research purposes.

Due to the ambiguities in related laws, complexities in de-identifying protected data and the risk involved, the data is rarely shared for research purposes which negatively affect the medical research.

The paper mentions that it is challenging task than implied in the report to develop cryptographic mechanisms to properly anonymize records as required by secondary use considerations.

I need to read about data de-identification before providing my on views on this. However, those techniques should use proper protection against re-identification in order to maintain individuals’ health privacy and build trust in the health care system.

During the research, I came across a description of an interesting research project named "Cloud DNA" [2]. This project is said to investigate on how to enable scientists to share properly de-identified EHRs in the cloud for easy storage, sharing and retrieval.

6.  User Interaction/Dispute Resolution

User Interaction:
Among other factor that we discussed, user interfaces for patients, providers and administrators are eaqully improtant for a secure system.
The paper suggests the following areas to be explored with regard to this aspect:
1. User friendly mechanisms to deal with complexity of user-selected privacy preferences.
2. How much data to make available to patients in what format
3. Techniques for patients to delegate their access rights

Educating the patients on how to use a PHR service or patient's interface of an EMR system is very important aspect in realizing the goal of a widespread health information echo system. While informing them that they have the control of outside access to their records, it is important to highlight that more it is accessible to physicians, better the service they get.

When the patient signs up for a PHR service or a health care provider, he can be presented with a set of easily understandable questions which ultimately defines the access control policies of their medical records.

Dispute resolution
While it needs for patient to have access to and control of their records, should the patients given the right to correct their record? Or else how to resolve disputes on the information in the records? Most administrators do not like this since they can not always trust patients to keep their medical records honestly.
But the patients should be given the chance to raise any dispute against the records in their profile.

The paper illustrated following aspects to be explored with regard to this:
1. Developing way for patients to securely and privately monitor their health records.
2. Allowing ways for patients to dispute the records while preserving original records
3. Coming up with ways to resolve conflicts on the deisputed records

In my view: Patients should have access to all his EMRs and should be able to establish access control over them. But they should not be able to change the medical records as they wish. If there is dispute, or if  a patient suspects a particular report, there should be a way to mark it as suspected immediately - but could only be changed by an authorized medical officer after further tests etc.

7. Security Metrics

Though it is obvious that EMRs have benefits over traditional paper based medical records, there should be proper security metrics to gauge the level of information security/privacy provided by a particular health care information system.

The paper mentions that in order to provide such assessment/analisis, meaningful matrics should be well developed and accepted which opens up research problems on which current work is also going on. Since the domain is limited, the paper believes that matrics can be developed.

Challenges in developpping such metrics are the variety and complexity of threat models and diffculty of measuring potential flaws in Software.

Research problems related to this aspect are:
1. developing threat models covering both electronic and paper based medical records.
2. developing techniques to quantify level of risk associated with sw based health information system

Conclusion:

• I have been writing this series of blog posts about the security, privacy, access control and identity management aspects related to health care IT systems from the  understanding that I got from various sources and my experiences as well. This was mainly inspired by the paper[1] which provides a research road map on the same topic.

• The paper[1] is mainly based on the PCAST report 2010 and this PCAST report have caused some arguments in the field. However, the paper[1] and this blog series has only taken the technical requirements that it has highlighted into consideration to identify the research problems and this blog series doesn't  intend to support or unsupport the report.

• Although the research community has identified and actively working on the research problems pertaining to the subject, there are many obstacles as well, such as difficulty in obtaining testbeds and test data for research  due to the sensitivity and critical nature of the data. Therefore it has been hard for research to comeup with successful results without realistic and live data and also those results obtained from sample mock data are unlikely to be accepted by the community.

• No matter how technically strong the healthcare IT solution is, there should be adequate and non-ambiguous legislation to fully realize the goal of a nation wide health IT echo system.

• During my research on this, I've come across some active and interesting research efforts from some research groups such as Health & Medical Security Lab[3], SHARPS [4] , CERIAS [5], and MediVault [5].

• The paper[1] provides a good overall understanding of the security requirements of a healthcare information system. Most importantly, it provides a very good understanding about the current research problems in the area for a budding researcher who is passionate about carrying out research in security, privacy and access control aspects, outcome of which can be contributed to realize the vision of the secured and viable health IT echo system. 

Related work:
I have done a webinar on Security Patterns with WSO2 ESB for which I picked use cases from health care domain and it was when I first got interested in investigating further on the security, privacy and identity management requirements of healthcare IS. In that effort, I mainly referred MSc thesis on the topic : Security in SOA-Based Healthcare Systems by Richard Sassoon.

References:
[1] A Research Roadmap for Healthcare IT Security inspired by the PCAST Health Information Technology Report
[2] Cloud DNA
[3] Health and Medical Security Lab
[4] SHARPS
[5] CERIAS
[6] MediVault
[7] Security in SOA-Based Healthcare Systems

Towards a viable and secure health information system - Part 4

This is the fourth of the series of blog posts that I have been writting on the subject, which was mainly inspired by the paper[1].

For the clarity and the ease of summarizing, let me include the following diagram which illustrates the overall picture on the security requirements of a health information system.

In my previous three posts in this series, I have discussed about Identity Management/Authentication, Authorization and Auditing. In this post, I am going to write about what role cryptographic techniques play in healthcare IS.

4. Cryptographic Techniques
Confidentiality, integrity and non-repudiation are key security requirements that should be met by any health information system. Encryption, digital signature are the de-facto mechanisms of achieving them. However, traditional encryption mechanisms have major limitations in accomplishing the goals of a distributed, country wide health information echo system.

Let me discuss this further adhering to my usual format: i.e discussing views from the paper[1] and me.

•  As in any security sensitive system, data both at rest and on the wire should be encrypted.
• Traditional public key cryptography has limitations to be used in a health information echo system because of the complexity in exchanging keys used to decrypt the EMRs, among the authorized principals who may come from around the country.
• Therefore, keys used to encrypt the data (we can call this cryptographic authorization as well) are not attached to individuals, but attached to role/identity attributes.
• If encrypted data is stored in one machine, the keys to decrypt should be obtained from  another service which is separately managed.
• The metadata related to EMR(which was discussed in detail in my second post) which contains information about access control to EMRs, should be digitally signed.
• Some of the metadata can be encrypted as well. Since the EMRs should be able to be searched from anywhere in the country, the keys to decrypt the metadata should be known to secure search engines but only the authorized personal should be able to decrypt the actual EMR data.

• The paper highlights the research problems motivated by the above requirements.
• Developing techniques to support flexible key management policies 
• Paper recommends using Attribute Based Encryption (ABE) for cryptographic access control and identifies research problems along that line as:

                  - Developing techniques to specify and enforce access control for EMRs based on ABE
                  - Developing key management solutions for ABE
                  - Provide cryptographic mechanisms to properly anonymize records as required by secondary use considerations such as research.

Here are some of my thoughts on the usage of cryptographic techniques in healthcare information systems

• As the paper suggests, Attribute Based Encryption(ABE) would provide a scalable solution for the cryptographic needs of a health information system and also a solution for the key management requirements.The post[2] describes ABE in detail, in summary what happens is:
  "The plaintext is encrypted with a set of attributes. The KGS(Key Generation Server), which possesses the master key, issues different private keys to users after authenticating the attributes they possess".

• The same post[2] describes two flavors of ABE which are Key Policy - Attribute Based Encryption and Ciphertext Policy Attribute Based Encryption. I believe the second one is more scalable since the keys are issued for the attributes that a principal possesses and whether the given cipher text can or can not be decrypted by that key is determined by the access policy enforced in the cipher text.

• In the paper[4], Akinyele et al. have implemented a solution for self protecting EMRs using Attribute Based Access Control. There, they have used a standard format (CCR) and an automated policy engine which assign a access policy for each record in patients' EMRs using which the records are encrypted with ABE.

• However, there is huge trust placed on Key Generation Server for correctly authenticating and validating the attributes that a user possesses before issuing keys. Therefore necessary actions should be taken in order to prevent it being a central point of failure.

• Performance should also be considered along with security. Public key cryptography is known to posses performance bottlenecks than symmetric key cryptography. However, symmetric key cryptography also has its own limitations. The thesis[3] introduces a symmetric cryptographic approach for key management known as Attribute Based Group Key Management.

Above are based on some of my readings about privacy preserving cryptographic techniques which can be used to accomplish the requirements of healthcare IT systems.

Another area related to the above discussion that I need to explore further is privacy preserving secure searching techniques to make the necessary EMRs available for the authorized physicians when they submit the search query from any location in the country.

References:
[1] A Research Roadmap for Healthcare IT Security inspired by the PCAST Health Information Technology Report
[2] Attribute Based Encryption
[3] Privacy Preserving Access Control for Third Party Data Management Systems
[4] Self-Protecting Electronic Medical Records Using Attribute-Based Encryption

Towards a viable and secure health information system - Part 3

This is the third of the series of blog posts that I have been writting, inspired by the paper[1].

Let me include the following diagram which illustrates the overall picture on the security requirements of a health information system.

In my previous two posts in this series, I have discussed about Identity Management/Authentication and Authorization. In this post, I am going to write about another important aspect of health care IS which is auditing.

3. Auditing

Auditing helps mainly in investigations about frauds or security breaches. In order to recreate an incident, meaningful and useful audit logs should be readily available. Protecting audit log archives is another challenge to be addressed.

Let me discuss this further adhering to my usual format: i.e discussing views from the paper[1] and me.

• The report mentions that the actions like the ones below in a health IT system should be monitored and audited by a security infrastructure which is independently managed.- Actions taken by different principals interacting with the system such as accessing, modifying and deleting EMRs
  - The policies/information used to authorize those actions.
  - Changes to authorization policies.

• It highlights the need of protecting audit logs with cryptographic mechanisms such that they can not be deleted, changed or tampered even by the administrators.

• It also raises the need of facilitating the patients to review audit records pertaining to their EMRs.

• The paper[1] draws attention towards an important concern related to auditing. That is: although it is easy to log every action, it generates lot of volume which causes problems in storage and retrieving info & recreatingan event when an incident occurs.

• Research problems identified by the paper in this space:- Exploring techniques to create audit logs in such a way that we can recreate events as well as limit the amount to store.
  - Finding new approaches for storage and retreival and also user-friendly access to logs.

Let me note down some of my ideas with this regard:

• Distributed logging standards such as XDAS[2] can be used in for auditing at a certain layer in the distributed health IT echosystem.

• Efficient digital signature mechanism needs to be in place for integrity protection of the log.

• Cassandra storage can be used to overcome the issue of large volumes of audit logs and a parallel processing techniques such as MapReduce can be used to efficient processing of audit logs at the retrieval stage. (Cassandra has been used in WSO2 Stratos which is the open source cloud middleware platform offered by WSO2. There, each tenant is able to view logs specific to that particular tenant. Similar techniques can be used to make audit records related to EMRs of a particular patient available to that patient which is a requirement raised in PCAST report as well.)

References:
[1] A Research Roadmap for Healthcare IT Security inspired by the PCAST Health Information Technology Report
[2] Introduction to XDAS

Towards a viable and secure health information system - Part 2

I have started discussing the $subject in my previous post based on a research paper[1] that I happened to read.
This is the second post of the series. Lets again take a look at the following image which summarizes the key considerations with regard to security, privacy and identity management of a healthcare information system.

In my previous post, I have given an overall idea on security in health care IS and discussed the first aspect, which is Identity Management and Authentication.
In this post, I am going to take the second aspect into consideration..

2. Authorization

Since a health information system contains personal information with varying sensitivity, not only authentication is sufficient, but also the rights of the authenticated principals to access certain data should be validated - which we refer as authorization.

For an example, a patient's medical records should only be possible to access by an authenticated principal in the role of a physician and also only during his/her working hours, while clinical data can be accessed by nurses as well. On the other hand, researchers can access medical data only if they are properly de-identified.

There should be proper mechanisms in place to enforce such fine grained authorization.

Let me discuss this in terms of, what the paper[1] analyzes and what my views are, on the mechanisms to accomplish the security requirement of authorization.

• The PCAST report highlights that according to current regulations, it is not necessary to have patients' consent to disclose treatment/payment information in certain conditions. Therefore patients do not have control over privacy of their medical records which affects negatively to build and maintain public's trust in health care IT.

• Mentioning some background information, report advocates the idea of a universal language to exchange health information between different healthcare providers who may still have proprietary formats/schema of storing data. It proposes to use a language structured as individual data elements, together with metadata that provide an annotation for each data element. It can be an extensible markup language, where individual pieces of data can be tagged with context-sensitive metadata.

• Report envisions that such a data representation framework can enable fine grained authorization/privacy preferences where the consent for access each data element (authorization policy) is expressed through meta data attached to it. 

• The paper[1] believes that the data representation framework plays a big role in secured EMR system with fine grained access control, and illustrates how the above recommendations motivates interesting research problems such as:

          - how to programatically tag data based on a particular security/authorization policy

          - how to efffectively feed tagged-data elements to an policy engine to get the decision whether the   requested access is allowed or not.
          - how to efficiently parse and process tagged data elements.

Let me mention some of my views on this aspect:

•  Although I do not have much understanding to comment on meta-data tagged data elements[2], I too strongly believe that there should be fine grained authorization models employed which are also robust, efficient and scalable to achieve the level of privacy that the records in a healthcare IS needs.

• From my understanding about the authorization models used in the identity/privacy world, XACML is a good candidate to implement a fine grained authorization system for healthcare information echo system. It is a policy based mechanisms which is flexible for changing requirements and which facilitates to define fine grained authorization policies based on identity attributes of the principals.Other key attributes of a XACML based solution are: loosely coupled, externalized, centralized and standardized.

• A real world use case example of using a XACML based authorization solution for health care can be found at [3].

• Privacy preserving secure search is an interesting aspect brought to discussion by the PCAST report. Although the search engines aggregate relevant data from multiple providers and provide the result for a search query, engine itself can not see the data which is authorized to be seen only by the certain parties.

• Authorization delegation is another aspect which has not been taken into consideration in the above report and the paper. It is important when physicians and patients use various mobile devices to access EHR and PHR where constrained authorization delegation needs to be performed. Industry standard to accomplish this requirement is OAuth[4].

• I found an interesting research project description [5] which develops an security schema for Veterans Affairs (VA) which claims to provide a secure, manageable, portable, scalable and cost effective solution with fine grained access control in place and which is easily pluggable to the existing system.

In summary:
- Enabling to specify fine grained authorization rules based on privacy preferences and to enforce access control is a key aspect of a secure healthcare information system.
- It should be possible to realize such an authorization model even with existing legacy EMR systems with minimal or no change to the underlying persistent mechanisms.
- One strong mechanism suggested by PCAST report is to use metadata in a tagged data elements framework to achieve this which motivates several research problems.
- Some existing technologies and standards can be used to implement certain aspects of an authorization solution for a health information system such as XACML for fine grained policy based access control and OAuth for authorization delegation.

References:
[1]  A Research Roadmap for Healthcare IT Security inspired by the PCAST Health Information Technology Report
[2] Metadata and Meaningful Use
[3] XACML Sample for Health Care Application
[4] OAuth
[5] Trusted Medical Information System and Health Informatics

Identity Provisioning from On-Premise to Cloud

Quoting from one of my initial posts on SCIM:

"Today the enterprise IT solutions adopt products and services from multiple cloud providers in order to accomplish various business requirements. Hence it is no longer sufficient to maintain user identities only in corporate LDAP.

In most cases, SaaS providers also need dedicated user accounts created for the cloud service users, which raises the need of proper identity provisioning mechanisms to be in place."

Identity Server(IS) 4.0.0 which is a 100% open source Enterprise Identity & Entitlement Management Server, supports the open standard SCIM for identity provisioning as I have mentioned in my previous posts as well.

With this, WSO2 Stratos Live next release will also be supporting SCIM for Identity Provisioning.

This post is about implementing a use case of identity provisioning from on-premise to cloud using Identity Server and Stratos (here, same IS distribution can be used to simulate Stratos IS with multi-tenancy aspects).

Following diagram gives an overview of the deployment:

Use case:
Two organizations called wso2.com and willpower.org have their on-premise enterprise Identity Management Solutions running with Identity Server.
Both these organizations use cloud services offered by WSO2 StratosLive and have created tenants in there.
Now, they want to provision the user account, identity management operations such as creating/deleting users and groups, updating user identity attributes etc which happens in their on-premise Identity Server to the respective tenants they have in StratosLive, as shown in the above diagram.

Implementation:
In this case, Identity Server running inside the organizational boundaries of each organization act as SCIM consumers and the Identity Server as a Service running in StratosLive acts as a SCIM Service Provider.

Each organization can register SCIM provider configurations pointing to their tenant space in SLive, within enterprise IS instances.

Following is a step by step guide for this.
Step1: setup
Download and unzip IS distribution into three different folders (to represent  instances at: 1.wso2, 2.willpower, 3.SLive)

Increment Ports->PortOffset element in carbon.xml s.t three instances are running in following ports:
IS of WSO2: 9443
IS of Willpower: 9444
SLive IS: 9445

You can find more details on how to do this step from the step1 of my previous post.

Step 2: creating tenants
Login as admin to the IS instance that simulates Stratos IS in our setup and create two tenants named "wso2.com" and "willpower.com".

Screen shots of the steps shown below:

Step3: registering SCIM providers

Now login to IS instances of WSO2 and WillPower organizations as admin user and register SCIM provider configurations pointing to their respective tenant spaces in SLive IS instance.
For a more detailed guide on how to register SCIM providers, please refer to step3 of my previous post.
Example configurations shown below:

Step 4: testing provisioning

Now you can test creating/deleting/updating users, groups in organizational IS instances and verify that they are provisioned to particular tenant space of each organization in SLive IS instance.

That's it... Thanks..!

Identity Synchronization across Multiple Nodes with SCIM

We sometimes manage user identities in multiple nodes and we need to synchronize all the nodes when one node gets updated.

In this post we will look at how we can leverage SCIM - an open standard for identity provisioning, to achieve this requirement of Identity Synchronization.

As I have mentioned in my previous post, WSO2 Identity Server (IS) supports identity provisioning with SCIM, based on WSO2 Charon which is the implementation of the specification.

Identity Server can act as both SCIM Consumer and Service Provider.
To achieve the aforementioned requirement, we leverage both those capabilities of IS at once.

Let me describe a use case and then provides steps how to implement that with WSO2 Identity Server.

Use Case:

Lets say we have an organization which has multiple stores distributed across a region. Each store maintains a user store. And there is a central store as well. When one sub store updates its user accounts, that update should be propagated to central node and the central node sends that update to all the other sub stores.
If an update happens in the central node, that should also be propagated to all the sub stores.

Following diagram depicts this better: The directions that each node's updates propagate, are indicated by arrows with specific colour of each node.

Aside each node, I have listed a list of 'Provisioning Admins' along with their provider, if they have any.
Let me describe it. We send a provisioning request to a SCIM provider node from a consumer node. Therefore, we need to register providers at the nodes which plays the role of a consumer at a particular time.

And you need to have an account in the provider node, with proper permission to do provisioning. Because, as I mentioned in the previous post, SCIM Service Provider authenticates and authorizes your provisioning request and fulfils it only it is authenticated and authorized.

Lets implement the above scenario step by step so that you will have a better idea:

Step 1: Setting up three nodes..
Download Identity Server 4.0.0 and unzip it into three folders named: 'store1', 'central', 'store2'.
Since we are starting in the same machine, we need to change the port of set of each IS instance.
Go to [IS_Home]/repository/conf and open carbon.xml. In 'central' instance, make Ports->OffSet to 1 and in 'store2' instance, make Ports->OffSet to2.
Start the three instances.
Now our three instances are running in following ports.
store1: 9443
central: 9444
store2: 9445

Step 2: Registering Provisioning Administrators...
Lets now create user accounts in each node which has privileges to register SCIM providers and/or perform provisioning on behalf of each store, as listed in the above image.

Store1:
Got to management console of store1 IS instance by typing url: https://localhost:9443/carbon/ in a browser, login to management console as admin,admin and go to configure-> users and roles
Create 'centraladmin', 'store2admin' user accounts.
Also create a role called 'provisioning admin' and assign that role the above two users and the two permissions: 'login' and 'Identity Provisioning' as shown in the following diagram.

Now, centraladmin user has the permission to provision user account updates happen in central store, to store1. In this case, central store becomes a SCIM Consumer and store1 becomes a SCIM Service Provider.

And store2admin user has the permission to send provisioning requests to store 1, via central store in order to propagate updates happen in store 2.

Default admin account of store1, which has all the permission, provision the updates happen in store1, to central store.

In this way, please create the relevant provisioning admin user accounts in central store and store2 IS instances as well, as illustrated in the first diagram above and assign them to the provisioning admin role with the two permissions.

Step3: Registering Providers
Identity Server allows consumer nodes to register SCIM providers in two ways:

1. Registering global providers - any user management operation performed in a particular tenant space will be provisioned to the global providers.

2. Registering providers specific to particular user account - any user management operation comes through SCIM Service Provider endpoints of a particular node will be further provisioned to the providers registered under the account from which SCIM requests was authenticated and authorized.

Lets look at how to register SCIM Providers at the central store in our scenario so that both above mechanisms will be clear to you.

1. Registering global SCIM providers at the central store.
According to our requirement, any user management operation performed by users in the admin role of central store should be provisioned to store1 and store2.
- Login as default admin user in central node (https://localhost:9444/carbon/admin/login.jsp)
- Access Main->Manage->SCIM

- Register New SCIM Provider.
We need to register both store1 and store 2 as global providers.
Following image shows the configuration of store1 SCIM provider.
Here we need to define a provier id, and provide user name and password to  authenticated and authorized to SCIM provider node(in this case it is centraladmin account which we registered in both store1 ans store2 in the previous step) and the URLs of the SCIM User & Group endpoints.

You need to register store2 also as a global provider with relevant configuration.

2. Registering SCIM providers specific to user accounts, at the central store.
According to our requirement, any provisioning request coming to central store from store1 should be provisioned to all the other sub stores except to store1.

Therefore, user account of the store1admin in the central store should be able to define to which providers my scim provisioning request should be further provisioned to, from the central node.

- Login to central node as store1admin.
- Access Main -> My Identity -> My SCIM Providers

- Now as the store1admin, you can register store2 as the SCIM Provider  by providing relevant configuration as shown below.

- And then login to central node as the store2admin account and register SCIM provider pointing to store1 endpoints.

Now we are done configuring central node for our provisioning scenario.

Then login to store1 and store2 IS instances as default admin and register central node as the global provider in both store1 and store2 as shown below.

Store1:

Store2:

 
Please refer the very first image in this post to make sure that you have created all the relevant provisioning admin user accounts in each IS node, given them proper permission and registered the corresponding SCIM providers as listed in that diagram for each node.

Step 4: Test Identity Synchronization
Now login to store1 as default admin and create a user account. Observe the logs at the backend console of each node. You will observe info logs mentioning that the user created at store1 is also created at central store and store2.

You can login to management console of central store and store2 and verify that the user created in store1 is listed in other two nodes as well.

You can perform other user and role management operations as well in each node and verify whether it is synchronized with other nodes as expected in our use case.

Following are the list of user management operations currently supported in WSO2 Identity Server to be provisioned via SCIM.
1. Create User
2. Delete User
3. Update credential of the user by admin
4. Update the profile of a user by admin
5. Update the profile of a user by the user himself
6. Create Group
7. Delete Group
8. Add users to group by updating group (Update user list of role)
9. Rename Group

Following are the list of user management operations allowed by WSO2 Identity Server, but not currently supported to be provisioned via SCIM.
1. Update credential of the user by user himself.
2. Add users to group by updating user (Update role list of user) - same outcome can be achieved by the no. 8 operation above.

I hope now it is clear to you how we can leverage SCIM - open standard for Identity Provisioning to achieve a use case of Identity Synchronization across multiple nodes using the capabilities of WSO2 Identity Server.

Configuring provisioning through configuration file
Identity Server also supports configuring SCIM providers through configuration file, in addition to allowing to register providers through UI which was explained above.
In this case, it is the admin of a particular node who configure providers which is different to individual provisioning admins registering SCIM providers through UI.

The relevant configuration file is: [IS_Home]/repository/conf/provisioning-config.xml

If you are configuring through configuration file, you need to follow the above steps until step 2 is completed.

Then shut down all the three IS instances. Replace provisioning-config.xml file of each instance with the ones shown below and restart the IS instances.

store1 configuration file:

    
        
            store1admin
            store1admin
            https://localhost:9444/wso2/scim/Users
            https://localhost:9444/wso2/scim/Groups
        
    
    
        
            
        
    

central store configuration file:

    
        
            centraladmin
            centraladmin
            https://localhost:9443/wso2/scim/Users
            https://localhost:9443/wso2/scim/Groups
        
 
            centraladmin
            centraladmin
            https://localhost:9445/wso2/scim/Users
            https://localhost:9445/wso2/scim/Groups
        
    
    
        
            
     
        
 
     
        
 
            
        
    

store2 configuration file:

    
        
            store2admin
            store2admin
            https://localhost:9444/wso2/scim/Users
            https://localhost:9444/wso2/scim/Groups
        
    
    
        
            
        
    

WSO2 Identity Server as a SCIM Service Provider

As I have blogged in my previous posts, we have developped WSO2 Charon as an open source implementation of SCIM protocol which is an open standard for Identity Provisioning.

It can be used by any one who wants to add SCIM based provisioning support for their applications.

We have integrated WSO2 Charon with WSO2 Identity Server 4.0.0which is available to be downloaded at http://wso2.com/products/identity-server/

In this post, I am going to demonstrate how to utilize its SCIM endpoints which expose User and Group resources in Restful way.

Following is a high level overview of SCIM Service Provider architecture of IS.

For simplicity, I will use curl commands to send CRUD requests to the rest endpoints of Identity Server.

Download Identity Server from above link, unzip it and start...

URL of the SCIM User Endpoint is: https://localhost:9443/wso2/scim/Users
URL of the SCIM Group Endpoint is: https://localhost:9443/wso2/scim/Groups

These endpoints are exposed over https since sensitive information is exchanged and also protected with Basic Auth Authentication.

Create User:
curl -v -k --user admin:admin --data "{"schemas":[],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","password":"hasinitg","emails":[{"primary":true,"value":"hasini_home.com","type":"home"},{"value":"hasini_work.com","type":"work"}]}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users

Here we authenticate with Basic Auth and send the payload in JSON format adhering to the SCIM 1.1 specification.

You will get a response with 201 CREATED status and pay load as below:
{"id":"48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","schemas":["urn:scim:schemas:core:1.0"],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini_home.com","type":"home"},{"value":"hasini_work.com","type":"work"}],"meta":{"lastModified":"2012-11-03T18:36:53","location":"https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","created":"2012-11-03T18:36:53"}}

There, you will notice that it contains some additional attributes such as unique id, created, last modified and location which are READ ONLY attributes and set by the service provider.

Now access the management console of Identity Server in a browse with URL:
https://localhost:9443/carbon/admin/login.jsp and login as admin with credential admin.

You will notice that the above created user is shown under:

Configure

> Users and Roles

> Users

You can access user profile of the user and see first name and last name are set properly but not other fields. That is because default claims of Carbon uses a different set of attributes in LDAP than the SCIM specific dialect (will discuss about it in detail later).

But those attributes are stored in the underlying user store. You can verify that by going a GET request on the User.

GET User:
You can retrieve a particular user resource using its unique id:

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215

You will notice that all the attributes that were sent are there in the response as well.

List Users:
Now create some users through the web management console of Identity Server and fill in their profile details. I created two users called Umesha and Shyama and filled in their profile details.

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users

Response:

{"schemas":["urn:scim:schemas:core:1.0"],
"totalResults":3,
"Resources":
[
 {"id":"48f7cfe5-f0e3-4a67-af7e-d762aa9ab215","name": {"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini_work.com","type":"work"},{"value":"hasini_home.com","type":"home"}],"meta":{"lastModified":"2012-11-03T18:36:53","created":"2012-11-03T18:36:53","location":"https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215"}},

{"id":"8dd71de9-e2f9-47b7-a5d4-a5f3862950ff","profileUrl":"shyama@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"shyama","givenName":"Shyama"},"userName":"shyama","emails":["shyama@example.com"],"phoneNumbers":[{"value":"7890","type":"mobile"}],"addresses":[{"value":"Panadura","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:53:46","created":"2012-11-03T18:52:41"}},

{"id":"6b14c23d-4811-4bbd-b653-04fcda2df266","profileUrl":"umesha@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"umesha","givenName":"Umesha"},"userName":"umesha","emails":["umesha@gmail.com"],"phoneNumbers":[{"value":"857657","type":"mobile"}],"addresses":[{"value":"Pannipitiya","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:51:52","created":"2012-11-03T18:50:26"}}
 ]
}

You can see the three users representation with attributes in JSON format adhering to SCIM Schema.

Update User:
I am going to update the work and home email of user: hasinitg through following curl command:

Note: you have to use the correct SCIM ID by taking it either from create user response or from list user response.

curl -v -k --user admin:admin -X PUT -d "{"schemas":[],"name":{"familyName":"gunasinghe","givenName":"hasinitg"},"userName":"hasinitg","emails":[{"value":"hasini@wso2.com","type":"work"},{"value":"hasi7786@gmail.com","type":"home"}]}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Users/48f7cfe5-f0e3-4a67-af7e-d762aa9ab215

You will get a response with 200 OK response and a payload containing the updated user representation.

Delete User:
Now I will delete the user with userName 'shyama' which was created through management console of IS:

curl -v -k --user admin:admin -X DELETE https://localhost:9443/wso2/scim/Users/8dd71de9-e2f9-47b7-a5d4-a5f3862950ff -H "Accept: application/json"

You will get a response with status 200 OK and the user will be deleted from the user store.

In the same way, we can manage groups by performing CRUD operations on the Group resource endpoint.

Filter User:
Since CRUD operations have to be performed using SCIM ID which is unique to Service Provider, User REST endpoint also supports filter operation. You can filter users with userName which is considered as the unique user attribute in Carbon servers.

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Users?filter=userNameEqumesha

You will get a response like below from which you can extract the SCIM ID to perform rest of the operations.

{"schemas":["urn:scim:schemas:core:1.0"],"totalResults":1,"Resources":[{"id":"6b14c23d-4811-4bbd-b653-04fcda2df266","profileUrl":"umesha@blogspot.com","ims":["gmail"],"roles":["everyone"],"name":{"familyName":"umesha","givenName":"Umesha"},"userName":"umesha","emails":["umesha@gmail.com"],"phoneNumbers":[{"value":"857657","type":"mobile"}],"addresses":[{"value":"Pannipitiya","type":"streetAddress"},{"value":"Sri Lanka","type":"country"}],"meta":{"lastModified":"2012-11-03T18:51:52","created":"2012-11-03T18:50:26"}}]}

Create Group: 
You can create groups either with or without members.
Following command creates a group with a user.

Note: when creating a group with users, you need to have that user already existing in the user store and provide its unique id. So lets create a new group named: 'engineer'  with user 'umesha' as a member.

curl -v -k --user admin:admin --data "{"displayName": "engineer","members": [{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display": "umesha"}]}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups 

You will get a response with payload like below and a response status 201 CREATED:

{"id":"e8868723-30b2-4979-ae23-6d1de2e7d841","schemas":["urn:scim:schemas:core:1.0"],"displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"umesha"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}} 

You can observe in the management console of IS, that the new group is listed under roles  and user Umesha is listed under users of that group.

List Groups: 
Now lets create another role through IS management console and list all the groups. Create a group named: 'manager' without any users added to it.

Now list the groups: You can see both groups are listed.
{"schemas":["urn:scim:schemas:core:1.0"],
 "totalResults":2,"Resources":[
{"id":"e8868723-30b2-4979-ae23-6d1de2e7d841","displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"umesha"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}},

{"id":"3f26902e-c22b-48bc-ba0a-c197a5710b70","displayName":"manager","meta":{"lastModified":"2012-11-03T20:39:25","created":"2012-11-03T20:39:25","location":"https://localhost:9443/wso2/scim/Groups3f26902e-c22b-48bc-ba0a-c197a5710b70"}}
]}

Update Group: 
Now lets rename the group 'manager' to executive:

curl -v -k --user admin:admin -X PUT -d "{"displayName": "executive"}" --header "Content-Type:application/json" https://localhost:9443/wso2/scim/Groups/3f26902e-c22b-48bc-ba0a-c197a5710b70 

You will get a response with 200 OK status and full JSON representation of the updated group.

Delete Group: 
You can delete the group using the unique SCIM Id of the group. Following command will delete the group: 'executive'

curl -v -k --user admin:admin -X DELETE https://localhost:9443/wso2/scim/Groups/3f26902e-c22b-48bc-ba0a-c197a5710b70 -H "Accept: application/json" 

Filter Group: 
You can filter groups with the group display name. Following command will filter the group with display name: 'engineer'

curl -v -k --user admin:admin https://localhost:9443/wso2/scim/Groups?filter=displayNameEqengineer

Response:
{"schemas":["urn:scim:schemas:core:1.0",null],"totalResults":1,"Resources":[{"id":"e8868723-30b2-4979-ae23-6d1de2e7d841","displayName":"engineer","members":[{"value":"6b14c23d-4811-4bbd-b653-04fcda2df266","display":"umesha"}],"meta":{"lastModified":"2012-11-03T20:33:16","created":"2012-11-03T20:33:16","location":"https://localhost:9443/wso2/scim/Groups/e8868723-30b2-4979-ae23-6d1de2e7d841"}}]}