Creating Docker Image for WSO2 ESB

Docker is a Container, used for running an application so that container is separate from others and run safely. Docker has a straightforward CLI that allows you to do almost everything you could want to a container.
Most of these commands use image id, image name, and the container id depend on the requirement. Docker daemon always run as the root user. Docker has a concept of "base containers", which you use to build your containers. After making changes to a base container, you can save those change and commit them.
One of Docker's most basic images is called "Ubuntu" (which I have used in my sample described in this post)
A Dockerfile provides a set of instructions for Docker to run on a container.
For each line in the Dockerfile, a new container is produced if that line results in a change to the image used. You can create you own images and commit them to Docker Hub so that you can share them with others. The Docker Hub is a public registry maintained by Docker, Inc. that contains images you can download and use to build containers.

 With this blog post, I am creating a docker image to start wso2 ESB server. I have created the dockerfile below to create my image. 

FROM       ubuntu:14.04

MAINTAINER  Nipuni nipuni@wso2.com

RUN apt-get update

RUN sudo apt-get install zip unzip

COPY wso2esb-4.8.1.zip /opt

COPY jdk1.8.0_60.zip /opt

WORKDIR "/opt"

RUN unzip jdk1.8.0_60.zip

RUN unzip /opt/wso2esb-4.8.1.zip 

ENV JAVA_HOME /opt/jdk1.8.0_60

RUN chmod +x /opt/wso2esb-4.8.1/bin/wso2server.sh


EXPOSE 9443 9763 8243 8280 

CMD ["/opt/wso2esb-4.8.1/bin/wso2server.sh"]

FROM ------------>will tell Docker what image is to base this off of.
RUN   ------------->will run the given command (as user "root") using sh -c "your-given-command"
ADD   ------------->will copy a file from the host machine into the container
WORKDIR ------ >set your location from which you need to run your commands from
EXPOSE ---------->will expose a port to the host machine. You can expose multiple ports.
CMD -------------- >will run a command (not using sh -c). This is usually your long-running process. In this case, we are running the wso2server.sh script. 


Following are the possible errors that you may face while building the docker image with a dockerfile: 

Step 1 : FROM ubuntu:14.04

 ---> 1d073211c498

Step 2 : MAINTAINER Nipuni nipuni@wso2.com

 ---> Using cache

 ---> c368e39cc306

Step 3 : RUN unzip wso2esb-4.8.1.zip

 ---> Running in ade0ad7d1885

 /bin/sh: 1: unzip:  not found 

As you can see the dockerfile has encountered an issue in step 3 which is “unzip is not found” to run as a program. This is because we need to add all the dependencies to the dockerfile before using them. Dockerfile creates an image based on the basic image “ubuntu:14.04” which is just a simple Ubuntu image. You need to install all the required dependencies (in my case it would be unzip) before using them.

Step 5 : RUN unzip wso2esb-4.8.1.zip
 ---> Running in e8433183014c

 unzip : cannot find or open wso2esb-4.8.1.zip, wso2esb-4.8.1.zip.zip or wso2esb-4.8.1.zip.ZIP

The issue is docker cannot find the zip file. I have added my zip file as the same location of my dockerfile. While building the docker image, you need to copy your resources to docker instance location with “COPY” command.

Step 9 : RUN /opt/wso2esb-4.8.1/bin/wso2server.sh

Error: JAVA_HOME is not defined correctly.

 CARBON cannot execute java

We need JAVA_HOME environment variable to be set properly while running wso2 products. Docker support setting environment variables with “ENV” command. You can copy your jdk zip file similar to wso2esb-4.8.1.zip and set JAVA_HOME. I have added below commands to my dockerfile.

COPY jdk1.7.0_65.zip /opt

RUN unzip jdk1.7.0_65.zip

ENV JAVA_HOME /opt/jdk1.7.0_65

 After successfully creating the dockerfile, save it with name "Dockerfile" in you preferred location. Add wso2esb-4.8.1.zip and jdk1.7.0_65.zip to same location.

You can then run the saved  dockerfile with command below:

 sudo docker build -t wso2-esb .

 As result you can see the commands listed in the dockerfile are running one by one with final line "Successfully built <image-ID>".

 You can view the newly created image with "sudo docker images".

 You can then run your image with command "sudo docker run -t <Image-ID>". You should be able to see the logs while starting the wso2 server.

 You also can access the server logs with "sudo docker logs <container-ID>".

Claim Management with WSO2 IS

WSO2 Carbon supports different claim dialects. A claim dialect can be thought of as a group of claims. A claim carries information from the underlying user store.

Claim attributes in user profile info page:

In WSO2 IS each piece of user attribute is mapped as a claim. If you visit the user profile page for a specific user (Configure --> Users and Roles --> Users --> User Profile), you can view the user profile data (see figure 1 below).

Figure 1

As you can see there are mandatory fields (eg: Profile Name), optional fields (eg: Country) and read only fields (eg: Role).

You can add a new user profile field to the above page. If you visit Claim Management list (in Configure --> Claim Management), there are set of default claim dialects listed in WSO2 IS. Among them http://wso2.org/claims is the default dialect for WSO2 Carbon. You can follow the steps below to add a new field to the user profile info page:

1. Click on dialect http://wso2.org/claims . This will list down a set of claim attributes.
2. Lets say you need to add attribute "Nick Name" to the user profile page. 
3. Click on attribute "Nick Name" and "Edit" . There are a set of fields you can edit. Some important features are:
1. Supported by Default - This will add the attribute to the user profile page
2. Required - This will make the attribute mandatory to fill when updating user profile
3. Read-only - This will make the attribute read-only 
4. You can try actions listed above and add any attribute listed in the dialect (or add a new claim attribute using "Add new Claim Mapping" option)

There are some more useful dialects defined in WSO2 IS.

One such dialect is http://wso2.org/oidc/claim  which is defined for OpenID attribute exchange. Attributes defined in this dialect will be used when retrieving claims for user info requests (as I have described in my previous post on "Accessing WSO2 IS profile info with curl"  ).

How to add a value to a claim defined in OpenID dialect?

(This mapping is currently valid for WSO2 IS 5.0.0 and will get changed in a later release)
You can follow the steps below when adding a value to a claim attribute in the OpenID dialect.

1.  Start WSO2 IS and login.
2. Go to wso2 OpenID claim dialect. (http://wso2.org/oidc/claim)
3. Find a claim attribute that you need to add a value to. (eg: Given Name)
4. Go to User Profile page. This will not display an entry to add Given Name attribute. 
5. As I have described in the first section of this post add a new claim mapping to the default dialect for WSO2 Carbon (http://wso2.org/claims) with the name and the "Mapped Attribute (s)". (Eg: Add a new Claim with the following details: )
1.  Display Name : Given Name
2.  Claim Uri : given_name
3.  Mapped Attribute (s) : cn   ----> add the same Mapped Attribute in you OpenID claim attribute
4.  Supported by Default : check
5. Required : check
6. Now you have a new claim attribute added to the default dialect for WSO2 Carbon
7. If you visit the user profile page of a user you can add a value to the newly added attribute. 
8. If you retrieve user info as in "Accessing WSO2 IS profile info with curl" you can see the newly added value is retrieved in the format {<Claim Uri > : <given value>} eg: ({given_name : xxxxx})

Please note that if you still can't see the newly added value when retrieving user info, you may have to restart the server or retry after cache invalidates (after 15min).  

This claim mapping operate as follows:
 > When you add a value to a user profile field via the UI (eg: adding a value to "Full Name" will map the value with the mapping attribute "cn" of the claim).
 > Hence if there is any other claim attribute in OpenID dialect http://wso2.org/oidc/claim that has the same mapping attribute "cn" then, this will also get the value added above.
 > (Eg: say you have "Mapping Attribute"="cn" in the claim attribute "Full Name" in OpenID dialect http://wso2.org/oidc/claim), You can get the value you have entered in to the "Full Name" entry in the user profile.

Accessing WSO2 IS profile info with curl

The WSO2 Identity Server is able to implement the OpendID connect Client profile. This posts give a basic steps you can follow to retrieve profile info from WSO2 IS

You can retrieve the access token with the command below.

curl -X POST -H "Content-Type:application/x-www-form-urlencoded" <oauth2-token-url> --insecure --data "client_id=<client-id>&client_secret=<client-secret>&grant_type=client_credentials&scope=openid"

Please find a sample command below. Token url is https://localhost:9443/oauth2/token if you have a IS server with hostname “localhost” and no port offset is set. You can find the client id and client secret under the “OAuth/OpenID connect configuration” section of the service provider you are using. Please not that you need to set scope to “openid”

curl -X POST -H "Content-Type:application/x-www-form-urlencoded" https://localhost:9443/oauth2/token --insecure --data "client_id=1Kfz8ivbw0hqjoTbo1LbVTJl2f4a&client_secret=8c7d2hVE4p17_lIZ4FHOtWLJfQEa&grant_type=client_credentials&scope=openid"

Following is a sample output received.

{"scope":"openid","token_type":"bearer","expires_in":3300,"id_token":"eyJhbGciOiJSUzI1NiJ9.eyJhdXRoX3RpbWUiOjE0MzAzODkyNjEyOTIsImV4cCI6MTQzMDM5Mjg2MTI5Miwic3ViIjoiYWRtaW4iLCJhenAiOiIxS2Z6OGl2YncwaHFqb1RibzFMYlZUSmwyZjRhIiwiYXRfaGFzaCI6IlkyUXlNMk5pWTJNMFlqWXpZell4WkdKaE5HVmxNR0ZtTVRJNU1UUXpOZz09IiwiYXVkIjpbIjFLZno4aXZidzBocWpvVGJvMUxiVlRKbDJmNGEiXSwiaXNzIjoiaHR0cHM6XC9cL2xvY2FsaG9zdDo5NDQzXC9vYXV0aDJlbmRwb2ludHNcL3Rva2VuIiwiaWF0IjoxNDMwMzg5MjYxMjkyfQ.DC9jDagCCkOXYD4ZVF-9wNpddoTdH96B7Mw_3nGv-2lW9SiWvL600b4Cch2mNoFAao1QeGl9pAP4bvbVgJGuthunQxBJuTYLy2KCH5k5Hc9lQsZtEM5Z6yzQ7q2wWfu9il9Lya-gUXVnBJEd5ovqtwI40KSLvuZUoei7l3S8lZo","access_token":"cd23cbcc4b63c61dba4ee0af1291436"} 

Then we can use the access token retrieved above to view profile info with the curl command below.

curl -k -H "Authorization: Bearer <access-token>" <userinfo-edpoint>?schema=openid 

A sample command is as follows 

curl -k -H "Authorization: Bearer 7244fef5b5de362489c5b2ed16de9e" https://localhost:9443/oauth2/userinfo?schema=openid 

This will then retrieve the list of user info attributes that has not null values as the output below.

{"name":"admin","family_name":"admin","preferred_username":"admin","given_name":"admin"} 

If you have looked into identity.xml inside <IS-HOME>/ repository/conf, you can find the response builder class as follows, You can customize this extending the interface UserInfoResponseBuilder [1]. Sample implementation can be found in [2].

 [1]UserInfoResponseBuilder.java 
 [2]UserInfoJSONResponseBuilder.java