In any system, there should be users who access the system and consume the services provided by it. These users have their own characteristics. Some examples for these characteristics would be the first name, last name, address, telephone, email, date of birth of the user. A user can be described by these attributes. In Identity Management terminology, we call these characteristics as user claims. A set of user claims are given in the below image that can be used to identify different users in a system.
In WSO2 servers, instead of using the claims like first name, last name etc, we define claims using a URI. For example, the email address claim of the user is “http://wso2.org/claims/emailaddress” in WSO2 servers which is a URI. Similarly, the last name claim of the user in WSO2 servers is “http://wso2.org/claims/lastname” . So, if we describe the same user shown in above image in WSO2 claims terminology, it would be like following.
You can add your own claims to WSO2 servers and also you can modify the default provided claims as well. In the blog post I will discuss the important things that you need to know when managing user claims in WSO2 servers. For demonstration purpose, I use WSO2 Identity Server 5.1.0 version which is the latest released version by the time of this writing.
Let’s get started. First login to the management console and go to Main -> Claims -> List and then you see the available claim dialects. A claim dialect is a group of claims. The particular dialect that is associated with a user profile in WSO2 servers is the “http://wso2.org/claims” dialect. We call this as “default carbon dialect” or “WSO2 claim dialect” as well.
Once you go inside the WSO2 carbon dialect, you can see all the user profile claims that are added by default.
These default claims are defined in SERVER_HOME/repository/conf/claim-config.xml file in any WSO2 server. When you start the server for the very first time, it will read this file and store all the default claim dialects and default claims inside the internal database. (If you haven’t added your own database, this is the H2 database shipped with the server itself. You can find more information on the database tables from [1] ).
The claim dialects are stored in UM_DIALECT table of the internal database. A claim dialect has an ID which is auto generated in the database. (Here, the WSO2 carbon dialect has the ID generated as number 2 in my case)
All the claims read from claim-config.xml file at the server startup are stored in UM_CLAIM table. (You can query the UM_CLAIM table providing the dialect ID of the WSO2 carbon dialect to identify the user profile related claims).
So if you have a server that is not a fresh pack (very first startup is already done), then if you need to modify the claims, you cannot just change the claim-config.xml file. Because server will not read the file and modify claims as it would not be the first time startup. So if you want to modify claims, either you have to do it through the Management Console or else you can use the Claim Management API [2] provided as an Admin Service [3] of the server.
However if you have modified the claim-config.xml file, at a later point when you create a new tenant, the default claims of that tenant will be added by reading this file so your changes would get appeared for that new tenant. But this is not the case for super tenant and it happens only at the first server startup (or else if you remove database tables and re-run server with -Dsetup option).
Although you have so many default claims in WSO2 carbon dialect, when you view a particular user’s profile from the management console, you will not see all those claims.
You will see only a subset of those claims. Some claims will be required and some claims will be read only.
If you view a particular claim in WSO2 claim dialect, you would see following. (Here I am viewing the email address claim).
“Description” describes the user of the claim. The “Claim Uri” is the unique identifier for the claim. “Mapped Attribute” is the property name where the value of the user’s claim would be stored in underlying userstore. “Reqular Expression” is useful if value for this claim should follow some character pattern. For example, email address of the user should follow some format. This can be defined as a regular expression.
Then we come to the most important properties of a claim.
Whether to include this claim in the user’s profile when you view the profile in Management Console would be decided by the “Supported by Default” property. If it is set to true (checkbox is selected) this claim appears in user’s profile. Otherwise it will not be shown in the profile.
“Required” property decides whether this claim’s value is mandatory for a user profile. If this property is set to true (checkbox selected), user’s profile cannot be saved if the value for this claim is empty in the Management Console.
There can be some claims where the value is set from some other way. For example the user’s roles are added separately using the User Management feature of the server, but the role claim of the user displays the set of roles that the user is having. But we do not want to allow modifying the role claim value just by saving the user profile. So we can make this claim “Read Only” so that only through the User Management feature we can modify roles, but not by modifying the value of the claim. In such scenarios, Read Only property is useful in claims.
When you fill the user profile details for a user and save the profile, the values would be stored in the underlying userstore. Here is an image where in Identity Server, user is stored in the underlying LDAP.
If you are using a JDBC userstore [4], the user’s attributes would be stored in UM_USER_ATTRIBUTE table.
From above details, I hope you got some basic idea about user claim and the user profile in WSO2 servers. There are some advanced concepts as well that are related to claims and I will discuss them in a future post.
References
Tharindu Edirisinghe
Platform Security Team
WSO2
No comments:
Post a Comment