WSO2 App Manager - Using JWT to send application user details to Backend Application

JSON Web Token (JWT) is a means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is digitally signed using JSON Web Signature (JWS) and/or encrypted using JSON Web Encryption (JWE).

For more information regarding JWT configuration with WSO2 AppM please refer below articles.

https://docs.wso2.com/display/APPM110/Passing+End+User+Attributes+to+the+Backend+Using+JWT

http://sumedha.blogspot.com/2012/08/using-jwt-to-send-application-user.html

How to Configure samples:

https://docs.wso2.com/display/APPM100/Demonstrating+JSON+Web+Token+(JWT)+Usage+-+Plan+Your+Trip+App

Here I'm trying to provide a sample .NET backend application which decode the JWT token and retrieve the Last name 

To test this, you need to build this application and host the binary in a IIS server. Then create a WebApp in WSO2 AppM and provide the relevant url as the backend url.  Also do not forget to add the 'lastname' as a claim mapping as explained in above articles.

Sample code to read header token values using ASP.NET (with C#.NET back end)

namespace Sample{
 public partial class _Default: System.Web.UI.Page {
  protected void Page_Load(object sender, EventArgs e) {
   try {
    if (!Page.IsPostBack) {
     //store the value of claim :http://wso2.org/claims/lastname
     String lastName = "";

     //check for X-JWT-Assertion parameter
     if (Request.Headers["X-JWT-Assertion"] != null) {
      reqHeader = Request.Headers["X-JWT-Assertion"].ToString();
      string[] stringSeperator = new string[] {
       "=."
      };
      //split the encoded string and send to decode
      string decodedHeader = base64Decode(reqHeader.Split(stringSeperator, StringSplitOptions.None)[1].ToString() + "=");
      decodedHeader = decodedHeader.Replace("\"", "'"); //format json string
      JObject obj = new JObject();
      obj = (JObject) JsonConvert.DeserializeObject(decodedHeader); //Decode Object

      if (obj["http://wso2.org/claims/lastname"] != null) {
       lastName = obj["http://wso2.org/claims/lastname"].ToString();
      }

     }
    }
   } catch (Exception ex) {
    //lblErr.Text = "Error: " + ex.Message;
   }

  }

  //base64 decodes the given encoded string (data :encoded string)
  public string base64Decode(string data) {
   try {
    System.Text.UTF8Encoding encoder = new System.Text.UTF8Encoding();
    System.Text.Decoder utf8Decode = encoder.GetDecoder();
    byte[] todecode_byte = Convert.FromBase64String(data);
    int charCount = utf8Decode.GetCharCount(todecode_byte, 0, todecode_byte.Length);
    char[] decoded_char = new char[charCount];
    utf8Decode.GetChars(todecode_byte, 0, todecode_byte.Length, decoded_char, 0);
    string result = new String(decoded_char);
    return result;
   } catch (Exception e) {
    throw new Exception("Error in base64Decode" + e.Message);
   }
  }
 }
}

More samples: 

Decode WSO2 App Manager generated JWT in PHP Web App

WSO2 App Manager - How to Create a Web Application

WSO2 App Manager - Web Application Creation end user configuration guide

In this post I'm trying to discuss the configuration options available in creating a WebApp.

To create a Web Application you need to log into publisher with an user who has the "Internal/creator" (or "admin") Role.

URL: http://<IP_ADDRESS>:9763/publisher

Login to Publisher > Click on Web Applications >  Add New Web Application

Overview section

Overview Properties:
Author	Username of the user who publish the app
Name	Application name (for internal usage only)
Display Name	Application Display Name
Context	URL Context
Version	Version of the Application (eg: 1.0, 1.1, 2.0)
Make As Default Version	When creating a new Application this is always set as marked and later when you create another version of the same Application you can swap the default versions (Please refer wso2-app-manager-multiple-versioning for more information)
Transports	Transport protocol (either HTTP or HTTPS)
Treat as a Site	If you select this, the published App will be act as a Site. (WSO2 AppM supports 3 type of Application types. WebApps, Mobile Apps and Sites)
Web App URL	Back end actual URL of the Application (eg: http://wso2.com)
Description	Description about the Application
Thumbnail	You can browse the image of the Thumbnail to be displayed
Banner	You can browse the image of the Banner to be displayed
Tags	You can define multiple tags against each application which will be useful when searching Apps by keywords (eg: HR, Educational, Engineering, etc)

Policies Section

Under Policies we have 2 main categories:

• Global Policies : Global Policies are applied agains an Application
• Resource Policies: Resource Policies are applied agains the selected resource patterns of an Application

Global Policies

Global Policy properties:
Allow Anonymous Access	Make the whole App anonymously accessible. In the Store, users will be able to access the app (all the resources  patterns inside the app) without login in. Eg: We we mark http://wso2.com as anonymous, users will be able to access any page inside (eg: http://wso2.com/contact/ , http://wso2.com/partners/) anonymously (Please refer wso2-app-manager-anonymous-app-support for more information)
Skip Creating Proxying WebApp	This will skip the gateway. It will allow users to directly access the back end actual URL without going through the gateway(proxy). So in the Store - overview page it will show the actual back end URL
Restrict Visibility	Configuration of Role Based Visibility in WSO2 AppM. You can specify the Roles which are eligible to access the App. So in the Store only Users with the particular Roles (and of course the users with Admin Role) will only be able access/view the App (Please refer wso2-app-manager-role-based for more information)
Enable Single Logout	You can define a custom Single Sign Out URL
Publish Statistics	Enable publishing statistics to BAM
Subscription Availability	Controls the subscription availability. WSO2 AppM allow users to subscribe to Apps in multiple tenants. Here you can control the subscription levels.  There are 3 options available: current_tenant : Only the users in current tenant will be eligible to subscribe all_tenants : Users in all tenants will be eligible to subscribe specific_tenants : Users in specified tenants will be eligible to subscribe

Resource Policies

Resource policies are applied agains selected resource patterns in an application. 

When you need to apply several restrictions to some particular resource in a app you this will be useful.

Eg:

You have http://wso2.com as your back end but you need to add a throttling policy to a certain page (lets say http://wso2.com/register/) to limit access, Resource policies will be needful.

WSO2 AppM supported Resource based Policy types:

• Throttling : Controls/restrict the concurrent requests
• Anonymous Access: Allow users to anonymously access the resource pattern(s)
• Role based Restrictions: Grant access to users with selected Role(s)
• XACML policies (Entitlement policies): You can define XACML based authorization policies and apply against resource pattern(s) 

There are two steps you need to follow:

• Define a Policy Group with required policy combination
• Apply the Policy Group against each Resource Pattern

When you are creating a new Application a default Policy Group with below default policy combinations are created by default. You can either change the properties or create new policy groups according to your requirement.

Default Policy Group settings:

• Throttling : Unlimited
• Anonymous Access: False
• Role based Restrictions: None
• XACML policies (Entitlement policies): None

To create a Policy Group:

Expand Policies > Resource Policies  and click on "Add new Resource Policy" button.

Resources based Policy properties:
Resource Policy Name	Name of the policy Group
Description	Description about the policy group
Apply Throttling Tier	Select a Throttling Tier from available Tiers (Unlimited/ Gold/ Silver/ Bronze) Default concurrent access limits are: Unlimited: Unlimited no of accesses Gold: 20 Silver: 5 Bronze: 1 For the Anonymous users throttling tier will not be applied and it always be unlimited. (Technical tip: You can customerize the tier setting as per your requirement by altering the tiers.xml file in /_system/governance/appmgt/applicationdata/ registry location)
Allow Anonymous Access	True/False Select 'true'  to make the Resource pattern anonymously accessible (Please refer wso2-app-manager-anonymous-app-support for more information)
Accessible User Roles	Role based restriction for Resource patterns. You can specify the Roles which are eligible to access the particular Resource Pattern. So in the Store only Users with the particular Roles (and of course the users with Admin Role) will only be able access/view the particular Resource Pattern (Please refer wso2-app-manager-role-based for more information)
Entitlement Policy	You can define a XACML Policy in the admin-dashboard and apply the policy here.

How to edit/delete policies in Policy Group?

Edit: Click on  icon to edit existing Policy Group details.  But the policy changes will be effective once the cache is reset.

Detele: Click on  icon to delete a Policy Group. It will only allow to delete the un assigned policy group(s) for any resource pattern.

How to assign a policy group to a particular resource pattern?

Under "Web Application Resources" section all the resource patterns will be listed in a grid view. 

And under "Resource policy" column you can choose the relevant policy group agains each resource pattern.

Web Application Resources Section

Navigate to "Web Application Resources" section. 

Here you can add multiple resource patterns and assign custom policies.

Web Application Resources properties:
URL Pattern	URL Pattern (Resource Pattern) is a sub domain or a page in side the actual endpoint of the Application. Eg: Actual End point of the App: http://wso2.com URL Pattern1: register (refers http://wso2.com/register) URL Pattern2: contact (refers http://wso2.com/contact)
HTTP Verb	Either GET/POST/PUT/DELETE/OPTION
Resource Policy	Select the appropriate resource policy. By default, "Default" policy group is assigned to all patterns initially. If you assign any policy group against /{context}/{version} /* it will be applicable for all the resources with the relevant HTTP Verb.  Eg:  URL Pattern:  /{context}/{version} /* HTTP Verb: GET Resource Policy: Anonymous-Group In this case the Anonymous-Group policies will be applicable for all the GET operations (all underneath URL Patterns as well). So another URL pattern like below will be override the permissions for mentioned resources. URL Pattern:  /{context}/{version} /register HTTP Verb: GET Resource Policy: Default

How to add a new resource pattern? 

Type the URL Pattern, select the HTTP Verb and click on "Add Resource" button.
By default, the "Default" policy group will be assigned as Resource Policy and you can select the relevant Resource Policy from defined list.

Advanced Configuration Section

Claims

In this section you can add claims against the newly created application.

What is a Claim?

Please refer https://docs.wso2.com/display/APPM100/Claim+Management

Here you can find details about what is a Claim, how to add new mappings and many more details.

A claim be use as a container to pass specific attributed to back end service via a JWT (https://docs.wso2.com/display/AM190/Passing+Enduser+Attributes+to+the+Backend+Using+JWT)

How to add Claims?

Select the required claim from the "Available Claims" drop down and click on "Add Claim" button.

OAuth2 Key Manager Configuration

OAuth2 Key manager configurations can be stored here.

What is it?

WSO2 AppM supports SAML SSO to authenticate an user. If your backend application uses internal OAuth API calls you can use this feature to use the same SAML token generated by WSO2 AppM gateway, and get an OAuth2 access token by calling the token endpoints used by these APIs. 

(Please refer https://docs.wso2.com/display/APPM110/Obtaining+an+OAuth2+Token+by+Providing+a+SAML+Token for further information)

OAuth2 Key Manager Configuration properties:
API Name	Alias for the API
API Consumer Key	Consumer Key of the OAuth API
API Consumer Secret	Consumer Secret of the OAuth API
API Token Endpoint	URL of the token endpoint used by API

How to View the created WebApps and Sites

Once the WebApp/Site is Created successfully, it will be listed under Publisher listing page.
(Login to Publisher > Web Applications > All Web Applications)

WebApp/Site  Listing:

Edit an Application

To Edit the Apps you can simply navigate to app listing page and click on any app, do the changes and update.

Here you need to know that, you wont be able to change the app name,context and version.
If you need, you can change the display name. And if you need to change a version you can follow wso2-app-manager-multiple-versioning for more information.

Using REGEX

Summary of Regular Expression Constructs

(Source: Oracle Website)

Characters
width="132"x	The character x
\\	The backslash character
\0n	The character with octal value 0n (0 <= n <= 7)
\0nn	The character with octal value 0nn (0 <= n <= 7)
\0mnn	The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)
\xhh	The character with hexadecimal value 0xhh
\uhhhh	The character with hexadecimal value 0xhhhh
\x{h…h}	The character with hexadecimal value 0xh…h (Character.MIN_CODE_POINT <= 0xh…h <= Character.MAX_CODE_POINT)
\t	The tab character (‘\u0009’)
\n	The newline (line feed) character (‘\u000A’)
\r	The carriage-return character (‘\u000D’)
\f	The form-feed character (‘\u000C’)
\a	The alert (bell) character (‘\u0007’)
\e	The escape character (‘\u001B’)
\cx	The control character corresponding to x

Character classes
[abc]	a, b, or c (simple class)
[^abc]	Any character except a, b, or c (negation)
[a-zA-Z]	a through z or A through Z, inclusive (range)
[a-d[m-p]]	a through d, or m through p: [a-dm-p] (union)
[a-z&&[def]]	d, e, or f (intersection)
[a-z&&[^bc]]	a through z, except for b and c: [ad-z] (subtraction)
[a-z&&[^m-p]]	a through z, and not m through p: [a-lq-z](subtraction)

Predefined character classes
.	Any character (may or may not match line terminators)
\d	A digit: [0-9]
\D	A non-digit: [^0-9]
\s	A whitespace character: [ \t\n\x0B\f\r]
\S	A non-whitespace character: [^\s]
\w	A word character: [a-zA-Z_0-9]
\W	A non-word character: [^\w]

Boundary matchers
^	The beginning of a line
$	The end of a line
\b	A word boundary
\B	A non-word boundary
\A	The beginning of the input
\G	The end of the previous match
\Z	The end of the input but for the final terminator, if any
\z	The end of the input

Example:

 import java.util.regex.Matcher;  
 import java.util.regex.Pattern;  
 public class RegexMatchesSample  
 {  
      private static String pattern = "^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\\.[A-Za-z0-9]+)*(\\.[A-Za-z]{2,})$";  
      private static Pattern customPattern = Pattern.compile(pattern);  
      public static void main( String args[] ){  
           String validEmail1 = "testemail@domain.com";  
           String validEmail2 = "test.email@domain.com";  
           String invalidEmail1 = "....@domain.com";  
           String invalidEmail2 = ".$$%%@domain.com";  
           System.out.println("Is Email ID : '" + validEmail1+ "' valid? - "+validateEmailID(validEmail1));  
           System.out.println("Is Email ID : '" + validEmail2+ "' valid? - "+validateEmailID(validEmail2));  
           System.out.println("Is Email ID : '" + invalidEmail1+ "' valid? - "+validateEmailID(invalidEmail1));  
           System.out.println("Is Email ID : '" + invalidEmail2+ "' valid? - "+validateEmailID(invalidEmail2));  
      }  
      public static boolean validateEmailID(String emailID) {  
           Matcher mtch = customPattern.matcher(emailID);  
           if(mtch.matches()){  
                return true;  
           }  
           return false;  
      }        
 }  

Result:
Is Email ID : 'testemail@domain.com' valid? - true
Is Email ID : 'test.email@domain.com' valid? - true
Is Email ID : '....@domain.com? - false
Is Email ID : '.$$%%@domain.com' valid? - false

WSO2 App Manager - Role Based Accessibility

Role Based Accessibility in WSO2 App Manager

In WSO2 App Manager you can restrict the visibility of Apps in the Store based on the user roles. 

To do this, when publishing an App you needs to select the "Restrict Visibility" option under (Policies > Global Policies) and mentioned the allowed roles. So the users who are assigned that particular role(s) and the users who are assigned the admin role only will be able to see the App in Store.

Eg: In this case, this App will be only visible to users who have "Role-developers" and "Admin" roles.

WSO2 App Manager - Anonymous App support

WSO2 AppM - Working with Anonymous Apps

Does WSO2 AppM support App access support for anonymous users?

Yes, when publishing an App you can define it as an anonymous access allowed App.
Also there is a option to make particular resources anonymously accessible in a non anonymous App,

Eg:
Option 1:
Lets say we have App called 'wso2-site' where the backend is www.wso2.com
We can make the complete App anonymous by selecting a single tick.

Option 2:
Let say we have a App called   'wso2-site' where the backend is www.wso2.com.
This App required authentication(anonymous access is not allowed) but, we need to give access to a particular resource (eg: http://wso2.com/contact/). WSO2 AppM supports this requirement.

How to publish an anonymous App?

• Login to publisher and click on 'Add New Web Application'
• Create an App selecting the  'Allow Anonymous Access' option under (Policies > Global Policies)

• Access the store as an anonymous user (without login). User should be able to access the App without authentication

How to publish a non-anonymous App with anonymous resources?

• Login to publisher and click on 'Add New Web Application'
• 'Allow Anonymous Access' option under (Policies > Global Policies) should be un ticked

• Click on 'Add New Resource' button under 'Resource Policies' tab

• Need to create a policy group with 'Allow Anonymous Access' option set as 'true'

• Add relevant anonymously allowed resource patterns and assign anonymous policy group

Tips: 

• If user assign the anonymous policy group to all the resources, the App itself will act as an anonymous App. 
• Similarly user can assign policy group to a HTTP verb wise as well (Eg: make all GET operations anonymously allowed but restrict DELETE operations)

WSO2 APP Manager - Multiple versioning support

How to configure WSO2 AppM to allow multiple version support

In WSO2 AppM applications can be accessed with and without app version mentioned in the URL.
Once an user publish an app as the default version, the particular app version can be accessed without specifying the version in the URL

eg:
Lets say I create a app with below details:

• Provider: lahiru
• App Name: myapp1
• App Context: myapp1
• Version: 1.0
• Is default version: true

In this case, technically two synapse configuration xml's will be created (under wso2appm-home/repository/deployment/server/synapse-configs/default/api) as versioned and non versioned apis. (in this scenario it will be lahriu--myapp1.xml and lahriu--myapp1_1.0.xml)
and the non versioned configuration will keep the default version details, So once a request received without a version it will redirected to the versioned app.

Tips:

• Non Versioned config will be only created if the published app is the default version (alone with the versioned config)
• Once a non default app version is published, only the Versioned Config will be created
• Once the default app version is unpublished/deleted Non Versioned config will be deleted alone with the Versioned config
• Once a non default app version is unpublished/deleted Non Versioned config will be remain as it is while Versioned config will be removed.

Database details:

Version update will be maintained in APM_APP_DEFAULT_VERSION table.

When an app is created the default version will be stored in DEFAULT_APP_VERSION field and once it is published PUBLISHED_DEFAULT_APP_VERSION field will be updated.

(Publihser UI always refer the DEFAULT_APP_VERSION field when idenfifying default version while Store UI refers the PUBLISHED_DEFAULT_APP_VERSION field)

User Experience (Publisher) :

• When you create a new application, you can define if it is the default version or not (select make as Default Version option)

• User can create a new version of any App marking the new version as the default version. So when the new app get published, all the subscription to the original version will be copied to the newly published version.

• User can also edit and mark any version of an existing App as the default version.

• There can be only one published default version of an App.

User Experience (Store) :

There are two deployment options available:

• Display all published versions 
• Display only the default version

To do this need to open app-manager.xml file inside [wso2appm_home]/repository/conf/ directory

Change the 'DisplayMultipleVersions' property to true/false accordingly

If display all published versions is enabled, it will show all the versions available in store/search result and all sorting options. But if you select display only the default version option it will show only the default version of the App in all occurrences.