Re: [Architecture] Swagger, API design and related best practices, and docs

[Lahiru Cooray]

Hi,
In AppM REST API developments we used Contract-first approach same as in
APIM (guideline [1]).
Since we did not have any REST API's we had to start from the scratch
(previously we had jaggery based API's and idea was to convert the logic
with proper REST naming conventions)
Contract-first approach helped us to do a proper designing before moving to
the implementation and easiness of generating client/server platform
independent stubs based on swagger annotations.

But in EMM scenario as you already have the defined API's (which are
already been used) I think a better approach will be, generating the
swagger definition with an annotation model (for existing API's) and in
next phase/version you can continue with Contract-first approach with the
generated swagger def.

[1]
http://wso2.com/library/tutorials/2016/03/tutorial-how-to-turn-a-cool-idea-into-a-business-api-with-the-wso2-platform/

On Thu, Apr 28, 2016 at 3:16 PM, Dilshan Edirisuriya 
wrote:

> Hi Prabath,
>
> Just commenting by looking at the EMM/IOT current state (I do agree that
> there needs to be a proper standard on this). Although contract first
> approach looks far more clean, EMM/IOT already have APIs defined. Hence
> going with contract first approach could result in slight modifications to
> the APIs? Not sure whether its valid though. If it so when it comes to EMM
> case if there are customers using it, it could have an impact. Also why do
> we see different standards across different products like AppM and EMM?
> Naming conventions etc. are slightly different. Also how do you manage to
> version the APIs with this? In AppM I see a version available in URL path.
> Correct me if I am wrong.
>
> Regards,
>
> Dilshan
>
> On 28 April 2016 at 14:53, Prabath Abeysekera  wrote:
>
>> Hi Everyone,
>>
>> What I'm trying to do primarily is setting up Swagger-based docs for
>> EMM/IoTS related APIs. However, while I was looking deeper into this, came
>> across a few things that I need clarifications upon.
>>
>> *Code-first or Contract-first?*
>>
>> Right now it appears that there are two approaches being used in the
>> platform for API design and development.
>>
>> 1. Contract first approach, which utilizes composing the Swagger
>> definition upfront and then generating the API implementation out of it.
>>
>> (** I do understand that there's a whole big debate around different
>> developer communities as to whether REST needs a contract, except for the
>> HTTP protocol, at all. But, the primary intention of this thread is "not"
>> to jump into a similar argument :) )
>>
>> 2. Code first approach, which utilizes implementing the API first and
>> then generates Swagger definition to be used for documentation purposes,
>> etc.
>>
>> Each approach obviously has its own pros and cons. This is, therefore, to
>> see what needs to be/already have standardized as the best approach to go
>> about API design and implementation.
>>
>> If we consider contract-first approach, that looks more elegant and lets
>> us enable enforcing proper governance across the API design and
>> implementation process. For instance, folks can first work on the Swagger
>> definition as the contract, at the design phase and then go into the
>> implementations later on after verifying the resource definitions, etc. The
>> second approach, on the other hand, makes it easier for us to deal with in
>> terms of implementing complex and more coarse-grained HTTP APIs (which I
>> believe is a common-case in the platform?) and exposing their definitions.
>>
>> *Impact of this on API documentation*
>>
>> So, coming back to the topic of documenting APIs with what was discussed
>> earlier, if we go by the first approach, there we have the swagger
>> definition up-front so we wouldn't need to go for any annotation-based
>> models, etc and instead, can directly generate API documentation based on
>> the existing Swagger definition via an appropriate doc generator tool.
>>
>> In contrast, the code-first approach demands us to go for an
>> annotation-model or something similar to get the documentation done.
>>
>> Whichever the case would ultimately produce the same output, but I
>> thought, as a platform we need to stick to just one approach and document
>> it properly. So the question is, what would that be?
>>
>>
>> Cheers,
>> Prabath
>> --
>> Prabath Abeysekara
>> Technical Lead
>> WSO2 Inc.
>> Email: praba...@wso2.com
>> Mobile: +94774171471
>>
>> ___
>> Architecture mailing list
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>


-- 
*Lahiru Cooray*
Software Engineer
WSO2, Inc.;http://wso2.com/
lean.enterprise.middleware

Mobile: +94 715 654154
___

Re: [Architecture] [CDM-F] Making "Device Management Feature" a top level extensible construct in CDM-F

[Dilshan Edirisuriya]

Hi,

What are the plans to support device identity? There are several situations
where you need to consider device as a top level element rather than
associating it with users. Eg; picking the device from authentication
level,  adding throttling policies for device etc.

Regards,

Dilshan

On 28 April 2016 at 17:56, Prabath Abeysekera  wrote:

> Hi Everyone,
>
> As all know, CDM-F is a platform that allows folks to easily extend its
> plug-in model and seamlessly add support for new device types. So, ATM,
> "Device Management Plugin" is the primary top level construct that can be
> extended in the framework, to cater the aforementioned requirement.
>
> I'm proposing "Device Management Feature" too should be treated as a
> similar top-level extensible construct, particularly considering "EMM-like"
> scenarios, in which we ship a standard set of plug-ins, that needs to be
> extended to support a few new features. Here's why.
>
> Let's assume an organization is planning to deploy EMM to manage their
> devices. The list of "features" that needs to be managed by one
> organization might vary from that of another. Further, support for managing
> some of those might not even be available OOTB as part of EMM. To makes
> things more complicated, in certain cases, shipping all that sort of fancy
> features around OOTB in EMM wouldn't quite make sense as well. However, in
> the context of those adopting organizations, having the ability to control
> such features might be critical. As a result, there is always a possibility
> that these folks get lured into customize the existing functionalities if
> that level of extensibility is not available in the product.
>
> To cater the aforesaid requirement, the only option available right now is
> extending one of the existing plug-ins (with the new features) and then
> plugging the enhanced plug-in back into the product, which is somewhat a
> tedious task.
>
> To make things more easier for users, I propose making "Device Management
> Feature" an extensible construct, which can be utilized by the folks who
> want to extend an existing plug-in to seamlessly support new features that
> are not supported OOTB in the product. This can be thought of as something
> similar to the concept of "mediators" in the context of ESB as well.
>
> WDYT?
>
> Cheers,
> Prabath
> --
> Prabath Abeysekara
> Technical Lead
> WSO2 Inc.
> Email: praba...@wso2.com
> Mobile: +94774171471
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Sriskandarajah Suhothayan]

On Fri, Apr 29, 2016 at 6:47 AM, Farasath Ahamed  wrote:

> Hi Suho,
>
> Just to be clear, Are we going to use the Password Grant Type in the case
> where SSO is disabled or is it the Client Credentials grant type using the
> client_id and client_secret of the app created?
>
Sorry it should be  Password Grant Type in the case where SSO is disabled.

>
>
> Thanks,
> Farasath Ahamed
> Software Engineer,
> WSO2 Inc.; http://wso2.com
> lean.enterprise.middleware
>
>
> Email: farasa...@wso2.com
> Mobile: +94777603866
> Blog: blog.farazath.com
> Twitter: @farazath619 
>
> On Thu, Apr 28, 2016 at 10:28 PM, Sriskandarajah Suhothayan  > wrote:
>
>> Thanks Sumedha for the points, to make life easy for the gadget developer
>> we decided to add oAuth token retrieval to DS.
>>
>> Based on the offline discussion with Johann, Sinthuja and Geesara we
>> decided to support only the following scenarios for DS
>>
>> 1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
>> passing to the backend
>>
>> 2. If SSO is disabled, obtaining a token (OAuth2) using client credential
>> grant type and passing to the backend,
>> Here the username and password will be obtained at server login and the
>> token is generated at the same time.
>>
>> Sorry my bad it should be Password Grant Type!


In both cases we will be using DCR for client registration at the server
>> level, and same token will be used by all gadgets to access the secured
>> backend APIs.
>>
>> To access secured backend from the gadgets a oAuth2Client js service (shindig
>> features) will be implemented at DS, such that gadgets can talk to
>> backend using the oAuth2Client which will embed appropriate authorisation
>> header when sending.
>>
>> Regards
>> Suho
>>
>> On Thu, Apr 28, 2016 at 2:37 PM, Sinthuja Ragendran 
>> wrote:
>>
>>> Hi Sumedha,
>>>
>>> On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
>>> wrote:
>>>
 Geesara,
 This is a model that should be coming out of Dashboard perspective.

 If we take a look @ basic building blocks of DS, its (similar to what
 you have mentioned)
 - Gadget
 - Dashboard
 - Wizards
 - Dashboard Admin panel
 - etc

 Each of these elements should have a permission model associated per
 instance.

>>>
>>> Yeah +1, as per now the permission checks are not implemented for these
>>> operations, but we need to incorporate that as well.
>>>
>>>
 For example, defining "permission to view any gadget" is not enough.
 But rather it should be "permission to view Gadget X".
 Same should be extended for all other building blocks. (AFAIK, this is
 not there for gadgets as of now)

 These need to be stored @ gadget server level and evaluated b4
 rendering any gadget.

>>>
>>> Yeah, actually we are planning to implement the role based access
>>> control for gadgets and then again different views of the dashboard page
>>> based on roles.
>>>
>>>

 Permissions to BE
 
 Once presentation layer permissions are sorted, it becomes
 responsibility of Gadget / Dashboard author to figure out mapping
 those permissions to a backend API.

 There are multiple ways to do this based on how backend is secured.
 - Passing session cookie obtained @ login to backend
 - Obtaining a token (OAuth2) using session cooking (using an OAuth2
 grant type)
 - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
 - IdP enabled deployment

 Ensuring backend API's permission requirements match front end user's
 privileges is part of author's
 responsibility. This is not something DS product needs to worry about.

>>>
>>> Exactly, but I think there should be some API provided by DS server
>>> (shindig features), so that the users can just call the necessary methods
>>> with respective parameters to get oauth token. WDYT?
>>>
>>> Thanks,
>>> Sinthuja.
>>>
>>>
 If by any chance backend is written using WSO2 technologies, we can
 leverage concepts like
 - Sharing same identity provider for both DS and BE server
 - passing authorisation details from FE to BE using JWT/SAML Response /
 User profile


 Permissions when gadgets being embedded into other products without
 dashboard
 
 This is yet another perspective of the same problem. This also can be
 solved if we follow same principles
 mentioned above.
 - Having gadget instance level permission definition
 - Way to obtain a gadget by passing in authorisation details (using one
 of the methods mentions above)

>>>
 Same applies for dashboards.


 On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap 
 wrote:

> *Requirement:*
> *When dashboard retrieving 

Re: [Architecture] [C5] [Hamming] Audit logs in C5.

[Sameera Jayasoma]

Yes. We were looking into the ThreadContext class provided by Log4j. But
the problem is that each and every time a developer logs an audit log, he
has to set contextual information. We can avoid this by setting required
details to the CarbonContext at the time of login in.

On Thu, Apr 28, 2016 at 8:14 PM, Manuranga Perera  wrote:

> Hi,
>
> Can't we just use MDC [1]. Kernel can wrap it if needed, but I don’t see
> why.
>
> try {
>
>   MDC.put("reg-resource",resource.getId());
>
>   // do actual work with current resource
>
> } finally {
>
>   try {
>
>   MDC.remove("reg-resource");
>
>   } catch (Exception ex) {
>
>   //ignore, just catching so IDE wan't complain. MDC will never throw an
> IllegalArgumentException.
>
>   }
>
> }
>
> As for appending, we can write a custom layout that iterates through all
> MDC values and log them. I think some build-in layouts already do this [2],
> not sure.
>
> BTW, I think we should look at logging JSON if possible. This will make
> DAS analysis of data much easier.
>
>
>
> [1] https://logging.apache.org/log4j/2.x/manual/thread-context.html
>
> [2]
> https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/layout/JsonLayout.html
>
> On Thu, Apr 28, 2016 at 4:39 AM, Sameera Jayasoma 
> wrote:
>
>> Hi All,
>>
>> Audit logs or Audit trails contain set of log entries which describe a
>> sequence of actions which have occurred over a time period. From audit
>> logs, it is possible to trace all the actions of a single user or all the
>> actions or changes introduced to a certain module in the system etc.  E.g.
>> It captures all the actions of a single user from the point he logs in to
>> the application.
>>
>> In previous versions of the Carbon platform, we only had a logger called
>> AUDIT and a separate appender which appends audit logs to separate log
>> file.
>>
>> The only drawback of this approach is that we don't have a proper way to
>> capture contextual information. In each and every audit log, we need to
>> capture logged in user details, IP address of client etc. In the previous
>> approach developers have to log this information with each and every audit
>> log attempt. This is suboptimal IMO, we need to implement a mechanism where
>> developers gives only the log message and system should append all the
>> other information to the log. I see few ways to implement this.
>>
>> 1) Write a custom appender which write audit logs to the file with
>> contextual information.
>> 2) Provide API to log audit logs. We can extract contextual information
>> from the CarbonContext in both of these methods.
>>
>> Any thoughts.
>>
>> Thanks,
>> Sameera.
>>
>> --
>> Sameera Jayasoma,
>> Software Architect,
>>
>> WSO2, Inc. (http://wso2.com)
>> email: same...@wso2.com
>> blog: http://blog.sameera.org
>> twitter: https://twitter.com/sameerajayasoma
>> flickr: http://www.flickr.com/photos/sameera-jayasoma/collections
>> Mobile: 0094776364456
>>
>> Lean . Enterprise . Middleware
>>
>>
>> ___
>> Architecture mailing list
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
>
> --
> With regards,
> *Manu*ranga Perera.
>
> phone : 071 7 70 20 50
> mail : m...@wso2.com
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>


-- 
Sameera Jayasoma,
Software Architect,

WSO2, Inc. (http://wso2.com)
email: same...@wso2.com
blog: http://blog.sameera.org
twitter: https://twitter.com/sameerajayasoma
flickr: http://www.flickr.com/photos/sameera-jayasoma/collections
Mobile: 0094776364456

Lean . Enterprise . Middleware
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] The location of the wso2as-web.xml within Application Server structure

[Kishanthan Thangarajah]

+1, let's use the META-INF directory for our config files.

On Thu, Apr 28, 2016 at 4:48 PM, Chiranga Alwis  wrote:

> Hi,
> the all new wso2as-web.xml web application descriptor for WSO2 Application
> Server 6.0.0 is a configurations file reminiscent to Apache Tomcat's
> context.xml file.
>
> The primary reasons behind the introduction of this file are as follows:
> 1. Separate out the WSO2 specific configurations from those related to
> Tomcat in order to improve the usability.
> 2. Separate out the configurations which are configurable at web
> application level from those which are configurable at server level.
> 3. Provide the facility to set configurations globally, effective for all
> web applications and also to override those configurations at web
> application level for the desired web application(s).
>
> This file can be currently added to the /WEB-INF of a web
> application.
> But in my belief, since wso2as-web.xml file acts as a configurations file
> specific to WSO2 Application Server or more precisely an application server
> specific configurations file, this file should move
> to /META-INF folder.
>
> I found an accurate description about this from the book 'Professional
> Java for Web Applications' by Nicholas S. Williams. This description comes
> under the 'Directory structure and WAR Files' section of chapter 1 of the
> book. It is as follows:
>
> "You probably also noticed the presence of two different META-INF
> directories. This can be a source of confusion for some developers, but if
> you remember the simple classpath rules, you can easily differentiate the
> two. Like JAR file META-INF directories, the root-level /META-INF directory
> contains the application manifest file. It can also contain resources for
> specific web containers or application servers. For example, Apache Tomcat
> (which you’ll learn about in Chapter 2) looks for and uses a context.xml
> file in this directory to help customize how the application is deployed in
> Tomcat. None of these files are part of the Java EE specification, and the
> supported files can vary from one application server or
> web container to the next." (from page 14-15)
>
> Any suggestions and ideas with regards to the location of this file are
> highly appreciated.
>
> --
> Chiranga Alwis,
> Software Engineering Intern,
> +94 77 5930497
> +94 77 6368208
>



-- 
*Kishanthan Thangarajah*
Associate Technical Lead,
Platform Technologies Team,
WSO2, Inc.
lean.enterprise.middleware

Mobile - +94773426635
Blog - *http://kishanthan.wordpress.com *
Twitter - *http://twitter.com/kishanthan *
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Geesara Prathap]

On Thu, Apr 28, 2016 at 12:58 PM, Sriskandarajah Suhothayan 
 wrote:

> 1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
> passing to the backend


This part is already there right? or are we talking about a new
implementation?

Actually in existing implementation token is generated against cookie. It
is not actually a bearer token just a session id. To generate bearer token
we have to use SAML grant type.

On Fri, Apr 29, 2016 at 6:47 AM, Farasath Ahamed  wrote:

> Hi Suho,
>
> Just to be clear, Are we going to use the Password Grant Type in the case
> where SSO is disabled or is it the Client Credentials grant type using the
> client_id and client_secret of the app created?
>
>
> Thanks,
> Farasath Ahamed
> Software Engineer,
> WSO2 Inc.; http://wso2.com
> lean.enterprise.middleware
>
>
> Email: farasa...@wso2.com
> Mobile: +94777603866
> Blog: blog.farazath.com
> Twitter: @farazath619 
>
> On Thu, Apr 28, 2016 at 10:28 PM, Sriskandarajah Suhothayan  > wrote:
>
>> Thanks Sumedha for the points, to make life easy for the gadget developer
>> we decided to add oAuth token retrieval to DS.
>>
>> Based on the offline discussion with Johann, Sinthuja and Geesara we
>> decided to support only the following scenarios for DS
>>
>> 1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
>> passing to the backend
>>
>> 2. If SSO is disabled, obtaining a token (OAuth2) using client credential
>> grant type and passing to the backend,
>> Here the username and password will be obtained at server login and the
>> token is generated at the same time.
>>
>> In both cases we will be using DCR for client registration at the server
>> level, and same token will be used by all gadgets to access the secured
>> backend APIs.
>>
>> To access secured backend from the gadgets a oAuth2Client js service (shindig
>> features) will be implemented at DS, such that gadgets can talk to
>> backend using the oAuth2Client which will embed appropriate authorisation
>> header when sending.
>>
>> Regards
>> Suho
>>
>> On Thu, Apr 28, 2016 at 2:37 PM, Sinthuja Ragendran 
>> wrote:
>>
>>> Hi Sumedha,
>>>
>>> On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
>>> wrote:
>>>
 Geesara,
 This is a model that should be coming out of Dashboard perspective.

 If we take a look @ basic building blocks of DS, its (similar to what
 you have mentioned)
 - Gadget
 - Dashboard
 - Wizards
 - Dashboard Admin panel
 - etc

 Each of these elements should have a permission model associated per
 instance.

>>>
>>> Yeah +1, as per now the permission checks are not implemented for these
>>> operations, but we need to incorporate that as well.
>>>
>>>
 For example, defining "permission to view any gadget" is not enough.
 But rather it should be "permission to view Gadget X".
 Same should be extended for all other building blocks. (AFAIK, this is
 not there for gadgets as of now)

 These need to be stored @ gadget server level and evaluated b4
 rendering any gadget.

>>>
>>> Yeah, actually we are planning to implement the role based access
>>> control for gadgets and then again different views of the dashboard page
>>> based on roles.
>>>
>>>

 Permissions to BE
 
 Once presentation layer permissions are sorted, it becomes
 responsibility of Gadget / Dashboard author to figure out mapping
 those permissions to a backend API.

 There are multiple ways to do this based on how backend is secured.
 - Passing session cookie obtained @ login to backend
 - Obtaining a token (OAuth2) using session cooking (using an OAuth2
 grant type)
 - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
 - IdP enabled deployment

 Ensuring backend API's permission requirements match front end user's
 privileges is part of author's
 responsibility. This is not something DS product needs to worry about.

>>>
>>> Exactly, but I think there should be some API provided by DS server
>>> (shindig features), so that the users can just call the necessary methods
>>> with respective parameters to get oauth token. WDYT?
>>>
>>> Thanks,
>>> Sinthuja.
>>>
>>>
 If by any chance backend is written using WSO2 technologies, we can
 leverage concepts like
 - Sharing same identity provider for both DS and BE server
 - passing authorisation details from FE to BE using JWT/SAML Response /
 User profile


 Permissions when gadgets being embedded into other products without
 dashboard
 
 This is yet another perspective of the same problem. This also can be
 solved if we follow same principles
 mentioned above.
 - Having gadget instance level permission 

Re: [Architecture] Implementing proper security model for dashboard server

[Farasath Ahamed]

Hi Suho,

Just to be clear, Are we going to use the Password Grant Type in the case
where SSO is disabled or is it the Client Credentials grant type using the
client_id and client_secret of the app created?


Thanks,
Farasath Ahamed
Software Engineer,
WSO2 Inc.; http://wso2.com
lean.enterprise.middleware


Email: farasa...@wso2.com
Mobile: +94777603866
Blog: blog.farazath.com
Twitter: @farazath619 

On Thu, Apr 28, 2016 at 10:28 PM, Sriskandarajah Suhothayan 
wrote:

> Thanks Sumedha for the points, to make life easy for the gadget developer
> we decided to add oAuth token retrieval to DS.
>
> Based on the offline discussion with Johann, Sinthuja and Geesara we
> decided to support only the following scenarios for DS
>
> 1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
> passing to the backend
>
> 2. If SSO is disabled, obtaining a token (OAuth2) using client credential
> grant type and passing to the backend,
> Here the username and password will be obtained at server login and the
> token is generated at the same time.
>
> In both cases we will be using DCR for client registration at the server
> level, and same token will be used by all gadgets to access the secured
> backend APIs.
>
> To access secured backend from the gadgets a oAuth2Client js service (shindig
> features) will be implemented at DS, such that gadgets can talk to
> backend using the oAuth2Client which will embed appropriate authorisation
> header when sending.
>
> Regards
> Suho
>
> On Thu, Apr 28, 2016 at 2:37 PM, Sinthuja Ragendran 
> wrote:
>
>> Hi Sumedha,
>>
>> On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
>> wrote:
>>
>>> Geesara,
>>> This is a model that should be coming out of Dashboard perspective.
>>>
>>> If we take a look @ basic building blocks of DS, its (similar to what
>>> you have mentioned)
>>> - Gadget
>>> - Dashboard
>>> - Wizards
>>> - Dashboard Admin panel
>>> - etc
>>>
>>> Each of these elements should have a permission model associated per
>>> instance.
>>>
>>
>> Yeah +1, as per now the permission checks are not implemented for these
>> operations, but we need to incorporate that as well.
>>
>>
>>> For example, defining "permission to view any gadget" is not enough.
>>> But rather it should be "permission to view Gadget X".
>>> Same should be extended for all other building blocks. (AFAIK, this is
>>> not there for gadgets as of now)
>>>
>>> These need to be stored @ gadget server level and evaluated b4 rendering
>>> any gadget.
>>>
>>
>> Yeah, actually we are planning to implement the role based access control
>> for gadgets and then again different views of the dashboard page based on
>> roles.
>>
>>
>>>
>>> Permissions to BE
>>> 
>>> Once presentation layer permissions are sorted, it becomes
>>> responsibility of Gadget / Dashboard author to figure out mapping
>>> those permissions to a backend API.
>>>
>>> There are multiple ways to do this based on how backend is secured.
>>> - Passing session cookie obtained @ login to backend
>>> - Obtaining a token (OAuth2) using session cooking (using an OAuth2
>>> grant type)
>>> - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
>>> - IdP enabled deployment
>>>
>>> Ensuring backend API's permission requirements match front end user's
>>> privileges is part of author's
>>> responsibility. This is not something DS product needs to worry about.
>>>
>>
>> Exactly, but I think there should be some API provided by DS server
>> (shindig features), so that the users can just call the necessary methods
>> with respective parameters to get oauth token. WDYT?
>>
>> Thanks,
>> Sinthuja.
>>
>>
>>> If by any chance backend is written using WSO2 technologies, we can
>>> leverage concepts like
>>> - Sharing same identity provider for both DS and BE server
>>> - passing authorisation details from FE to BE using JWT/SAML Response /
>>> User profile
>>>
>>>
>>> Permissions when gadgets being embedded into other products without
>>> dashboard
>>> 
>>> This is yet another perspective of the same problem. This also can be
>>> solved if we follow same principles
>>> mentioned above.
>>> - Having gadget instance level permission definition
>>> - Way to obtain a gadget by passing in authorisation details (using one
>>> of the methods mentions above)
>>>
>>
>>> Same applies for dashboards.
>>>
>>>
>>> On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap 
>>> wrote:
>>>
 *Requirement:*
 *When dashboard retrieving data from some REST APIs which are secured,
 we do require proper security model in place in order to identify who can
 access this dashboard and at which level should it be done. In addition,how
 can dashboard be going to communicate with respective REST API securely?*



  

Re: [Architecture] Implementing proper security model for dashboard server

[Manuranga Perera]

On Thu, Apr 28, 2016 at 12:58 PM, Sriskandarajah Suhothayan 
wrote:

> 1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
> passing to the backend


This part is already there right? or are we talking about a new
implementation?


-- 
With regards,
*Manu*ranga Perera.

phone : 071 7 70 20 50
mail : m...@wso2.com
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] [C5] [Hamming] Audit logs in C5.

[Prabath Siriwardana]

Can we use XDAS for audit logs? XDAS defines a standard format based on
JSON to log audits...

Thanks & regards,
-Prabath



On Thu, Apr 28, 2016 at 1:39 AM, Sameera Jayasoma  wrote:

> Hi All,
>
> Audit logs or Audit trails contain set of log entries which describe a
> sequence of actions which have occurred over a time period. From audit
> logs, it is possible to trace all the actions of a single user or all the
> actions or changes introduced to a certain module in the system etc.  E.g.
> It captures all the actions of a single user from the point he logs in to
> the application.
>
> In previous versions of the Carbon platform, we only had a logger called
> AUDIT and a separate appender which appends audit logs to separate log
> file.
>
> The only drawback of this approach is that we don't have a proper way to
> capture contextual information. In each and every audit log, we need to
> capture logged in user details, IP address of client etc. In the previous
> approach developers have to log this information with each and every audit
> log attempt. This is suboptimal IMO, we need to implement a mechanism where
> developers gives only the log message and system should append all the
> other information to the log. I see few ways to implement this.
>
> 1) Write a custom appender which write audit logs to the file with
> contextual information.
> 2) Provide API to log audit logs. We can extract contextual information
> from the CarbonContext in both of these methods.
>
> Any thoughts.
>
> Thanks,
> Sameera.
>
> --
> Sameera Jayasoma,
> Software Architect,
>
> WSO2, Inc. (http://wso2.com)
> email: same...@wso2.com
> blog: http://blog.sameera.org
> twitter: https://twitter.com/sameerajayasoma
> flickr: http://www.flickr.com/photos/sameera-jayasoma/collections
> Mobile: 0094776364456
>
> Lean . Enterprise . Middleware
>
>


-- 
Thanks & Regards,
Prabath

Twitter : @prabath
LinkedIn : http://www.linkedin.com/in/prabathsiriwardena

Mobile : +1 650 625 7950

http://blog.facilelogin.com
http://blog.api-security.org
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Sriskandarajah Suhothayan]

Thanks Sumedha for the points, to make life easy for the gadget developer
we decided to add oAuth token retrieval to DS.

Based on the offline discussion with Johann, Sinthuja and Geesara we
decided to support only the following scenarios for DS

1. If SSO is enabled, obtaining a token (OAuth2) using SAML Token and
passing to the backend

2. If SSO is disabled, obtaining a token (OAuth2) using client credential
grant type and passing to the backend,
Here the username and password will be obtained at server login and the
token is generated at the same time.

In both cases we will be using DCR for client registration at the server
level, and same token will be used by all gadgets to access the secured
backend APIs.

To access secured backend from the gadgets a oAuth2Client js service (shindig
features) will be implemented at DS, such that gadgets can talk to backend
using the oAuth2Client which will embed appropriate authorisation header
when sending.

Regards
Suho

On Thu, Apr 28, 2016 at 2:37 PM, Sinthuja Ragendran 
wrote:

> Hi Sumedha,
>
> On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
> wrote:
>
>> Geesara,
>> This is a model that should be coming out of Dashboard perspective.
>>
>> If we take a look @ basic building blocks of DS, its (similar to what you
>> have mentioned)
>> - Gadget
>> - Dashboard
>> - Wizards
>> - Dashboard Admin panel
>> - etc
>>
>> Each of these elements should have a permission model associated per
>> instance.
>>
>
> Yeah +1, as per now the permission checks are not implemented for these
> operations, but we need to incorporate that as well.
>
>
>> For example, defining "permission to view any gadget" is not enough.  But
>> rather it should be "permission to view Gadget X".
>> Same should be extended for all other building blocks. (AFAIK, this is
>> not there for gadgets as of now)
>>
>> These need to be stored @ gadget server level and evaluated b4 rendering
>> any gadget.
>>
>
> Yeah, actually we are planning to implement the role based access control
> for gadgets and then again different views of the dashboard page based on
> roles.
>
>
>>
>> Permissions to BE
>> 
>> Once presentation layer permissions are sorted, it becomes responsibility
>> of Gadget / Dashboard author to figure out mapping
>> those permissions to a backend API.
>>
>> There are multiple ways to do this based on how backend is secured.
>> - Passing session cookie obtained @ login to backend
>> - Obtaining a token (OAuth2) using session cooking (using an OAuth2 grant
>> type)
>> - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
>> - IdP enabled deployment
>>
>> Ensuring backend API's permission requirements match front end user's
>> privileges is part of author's
>> responsibility. This is not something DS product needs to worry about.
>>
>
> Exactly, but I think there should be some API provided by DS server
> (shindig features), so that the users can just call the necessary methods
> with respective parameters to get oauth token. WDYT?
>
> Thanks,
> Sinthuja.
>
>
>> If by any chance backend is written using WSO2 technologies, we can
>> leverage concepts like
>> - Sharing same identity provider for both DS and BE server
>> - passing authorisation details from FE to BE using JWT/SAML Response /
>> User profile
>>
>>
>> Permissions when gadgets being embedded into other products without
>> dashboard
>> 
>> This is yet another perspective of the same problem. This also can be
>> solved if we follow same principles
>> mentioned above.
>> - Having gadget instance level permission definition
>> - Way to obtain a gadget by passing in authorisation details (using one
>> of the methods mentions above)
>>
>
>> Same applies for dashboards.
>>
>>
>> On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap 
>> wrote:
>>
>>> *Requirement:*
>>> *When dashboard retrieving data from some REST APIs which are secured,
>>> we do require proper security model in place in order to identify who can
>>> access this dashboard and at which level should it be done. In addition,how
>>> can dashboard be going to communicate with respective REST API securely?*
>>>
>>>
>>>
>>>  Figure 01:
>>> Dashboard Server
>>>
>>>
>>> Data providers for gadgets need to communicate with DS securely. Most of
>>> the cases data providers are some REST APIs. There might be a situation
>>> which dashboard will be getting data from different data providers as well.
>>> In the DS perspective, there must be an effective way to tackle these
>>> security related issues up to some extent. Referring to figure 1, we are
>>> having three places where we can address these issues.
>>>
>>>- gadget level
>>>- per-dashboard level
>>>- dashboard server level
>>>
>>> What would be the proper place which we can address security concerns in
>>> a proper 

Re: [Architecture] [C5] [Hamming] Audit logs in C5.

[Manuranga Perera]

Hi,

Can't we just use MDC [1]. Kernel can wrap it if needed, but I don’t see
why.

try {

  MDC.put("reg-resource",resource.getId());

  // do actual work with current resource

} finally {

  try {

  MDC.remove("reg-resource");

  } catch (Exception ex) {

  //ignore, just catching so IDE wan't complain. MDC will never throw an
IllegalArgumentException.

  }

}

As for appending, we can write a custom layout that iterates through all
MDC values and log them. I think some build-in layouts already do this [2],
not sure.

BTW, I think we should look at logging JSON if possible. This will make DAS
analysis of data much easier.



[1] https://logging.apache.org/log4j/2.x/manual/thread-context.html

[2]
https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/layout/JsonLayout.html

On Thu, Apr 28, 2016 at 4:39 AM, Sameera Jayasoma  wrote:

> Hi All,
>
> Audit logs or Audit trails contain set of log entries which describe a
> sequence of actions which have occurred over a time period. From audit
> logs, it is possible to trace all the actions of a single user or all the
> actions or changes introduced to a certain module in the system etc.  E.g.
> It captures all the actions of a single user from the point he logs in to
> the application.
>
> In previous versions of the Carbon platform, we only had a logger called
> AUDIT and a separate appender which appends audit logs to separate log
> file.
>
> The only drawback of this approach is that we don't have a proper way to
> capture contextual information. In each and every audit log, we need to
> capture logged in user details, IP address of client etc. In the previous
> approach developers have to log this information with each and every audit
> log attempt. This is suboptimal IMO, we need to implement a mechanism where
> developers gives only the log message and system should append all the
> other information to the log. I see few ways to implement this.
>
> 1) Write a custom appender which write audit logs to the file with
> contextual information.
> 2) Provide API to log audit logs. We can extract contextual information
> from the CarbonContext in both of these methods.
>
> Any thoughts.
>
> Thanks,
> Sameera.
>
> --
> Sameera Jayasoma,
> Software Architect,
>
> WSO2, Inc. (http://wso2.com)
> email: same...@wso2.com
> blog: http://blog.sameera.org
> twitter: https://twitter.com/sameerajayasoma
> flickr: http://www.flickr.com/photos/sameera-jayasoma/collections
> Mobile: 0094776364456
>
> Lean . Enterprise . Middleware
>
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>


-- 
With regards,
*Manu*ranga Perera.

phone : 071 7 70 20 50
mail : m...@wso2.com
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Security Authentication Analytics

[Damith Wickramasinghe]

Hi Sajith,

Sorry I have missed this. No for the first phase we are not focusing on
this.

Regards,
Damith.

On Tue, Mar 29, 2016 at 10:06 AM, Sajith Ravindra  wrote:

> Hi Damith,
>
> Do we support these statistics per tenant? So that each tenant can view
> these statistics per tenant.
>
> Thanks
> *,Sajith Ravindra*
> Senior Software Engineer
> WSO2 Inc.; http://wso2.com
> lean.enterprise.middleware
>
> mobile: +94 77 2273550
> blog: http://sajithr.blogspot.com/
> 
>
> On Mon, Mar 28, 2016 at 4:08 AM, Damith Wickramasinghe 
> wrote:
>
>> Sure.We will schedule.
>>
>> Regards,
>> Damith.
>>
>> On Mon, Mar 28, 2016 at 4:02 PM, Srinath Perera  wrote:
>>
>>> As per our chat, lets schedule a review.
>>>
>>> --Srinath
>>>
>>> On Sun, Mar 27, 2016 at 11:19 PM, Damith Wickramasinghe <
>>> dami...@wso2.com> wrote:
>>>
 Hi All,

 When it comes to Security analytics story we have broken it down to
 mainly three sections(Can be more in the future). Namely Authentication
 Analytics , Authorization Analytics and Audit trail for identity
 artifacts.  As for the first phase we are focusing on Authentication
 Analytics and Audit trail for identity artifacts.

 Data Summarization

 For Authentication Analytics when a user authenticates we are
 publishing related data from IS side for a raw table which will get
 persisted In DAS. Then using scheduled spark scripts we are summarizing the
 data to yearly,monthly,daily,hourly,minutely and secondly tables. (We may
 drop the secondly table since it may contain lot of data and will be not
 efficient when carrying out aggregate operations. Also these scheduled
 spark scripts will run incrementally without summarizing previous data
 again.)

 As per the [1] we have following charts.We are only considering login
 success and failure scenarios. (As discussed with IS team we dropped logout
 success and failure scenarios for now.Since showing those statistics are
 not much important.)

- overall authentication success and failure count during a time
range - Area chart
- per user Authentication success count - horizontal bar chart
- per user Authentication failure count - horizontal bar chart
- per role Authentication success count - horizontal bar chart
- per role Authentication failure count - horizontal bar chart

  etc. As above there are charts for service provider,identity
 provider,region and for ip ranges as well.

 Above Area chart for overall authentication success and failure count
 can be further drilled down as user clicks on horizontal bar charts(per
 user,per role etc). To cater this we have a one table structure with
 columns (if we take monthly table) Per month -> Per user -> Per roles ->
 Per serviceProvider -> Per identityProvider -> Per region -> Per Ip ->
 authSuccessCount and authFailureCount. Ill call this TABLE1.

 Please note in above table we are keeping the roles as comma separated
 values. so when a role is clicked we can identify authSuccess and
 authFailure count using DAS score function[2]. We discussed on getting this
 comma separated roles per event from IS directly since it will make things
 easier when it comes to summarization logic.

 For all other horizontal bar charts except role table , we are
 following below table structure.

 (If we take monthly table for user) Per month -> Per user
 ->authSuccessCount and authFailureCount . Ill call this TABLE2.

 Its true that these information can also be achieved from TABLE1. But
 since it has multi level grouped data, data aggregation will take more
 time. So having on level grouping will allow less records to be aggregated.

 For the role table we need a row for each role with corresponding
 authSuccessCount and authFailureCount. But as mentioned above since we are
 sending roles as comma separated values we do not have a efficient way to
 separate each role and construct the table. So we thought of getting the
 data as duplicated events(per user will have multiple roles so a event will
 be duplicated because of the role) from IS side and do the summarization.

 (If we take monthly table per role) Per Role -> Per User -> Per Service
 provider -> Per identity Provider -> Per region -> Per IP ->
 authSuccessCount and authFailureCount. Ill call this TABLE3.We have to go
 in to these grouping since we need drilled down info of roles per user, per
 service provider etc.

 So when it comes to user interactions , as per[1] he can click on per
 user login auth success table. According to the clicked user above Area
 chart, and all other horizontal bar charts should be changed for that user.
 

[Architecture] [CDM-F] Making "Device Management Feature" a top level extensible construct in CDM-F

[Prabath Abeysekera]

Hi Everyone,

As all know, CDM-F is a platform that allows folks to easily extend its
plug-in model and seamlessly add support for new device types. So, ATM,
"Device Management Plugin" is the primary top level construct that can be
extended in the framework, to cater the aforementioned requirement.

I'm proposing "Device Management Feature" too should be treated as a
similar top-level extensible construct, particularly considering "EMM-like"
scenarios, in which we ship a standard set of plug-ins, that needs to be
extended to support a few new features. Here's why.

Let's assume an organization is planning to deploy EMM to manage their
devices. The list of "features" that needs to be managed by one
organization might vary from that of another. Further, support for managing
some of those might not even be available OOTB as part of EMM. To makes
things more complicated, in certain cases, shipping all that sort of fancy
features around OOTB in EMM wouldn't quite make sense as well. However, in
the context of those adopting organizations, having the ability to control
such features might be critical. As a result, there is always a possibility
that these folks get lured into customize the existing functionalities if
that level of extensibility is not available in the product.

To cater the aforesaid requirement, the only option available right now is
extending one of the existing plug-ins (with the new features) and then
plugging the enhanced plug-in back into the product, which is somewhat a
tedious task.

To make things more easier for users, I propose making "Device Management
Feature" an extensible construct, which can be utilized by the folks who
want to extend an existing plug-in to seamlessly support new features that
are not supported OOTB in the product. This can be thought of as something
similar to the concept of "mediators" in the context of ESB as well.

WDYT?

Cheers,
Prabath
-- 
Prabath Abeysekara
Technical Lead
WSO2 Inc.
Email: praba...@wso2.com
Mobile: +94774171471
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Swagger, API design and related best practices, and docs

[Dilshan Edirisuriya]

Hi Prabath,

Just commenting by looking at the EMM/IOT current state (I do agree that
there needs to be a proper standard on this). Although contract first
approach looks far more clean, EMM/IOT already have APIs defined. Hence
going with contract first approach could result in slight modifications to
the APIs? Not sure whether its valid though. If it so when it comes to EMM
case if there are customers using it, it could have an impact. Also why do
we see different standards across different products like AppM and EMM?
Naming conventions etc. are slightly different. Also how do you manage to
version the APIs with this? In AppM I see a version available in URL path.
Correct me if I am wrong.

Regards,

Dilshan

On 28 April 2016 at 14:53, Prabath Abeysekera  wrote:

> Hi Everyone,
>
> What I'm trying to do primarily is setting up Swagger-based docs for
> EMM/IoTS related APIs. However, while I was looking deeper into this, came
> across a few things that I need clarifications upon.
>
> *Code-first or Contract-first?*
>
> Right now it appears that there are two approaches being used in the
> platform for API design and development.
>
> 1. Contract first approach, which utilizes composing the Swagger
> definition upfront and then generating the API implementation out of it.
>
> (** I do understand that there's a whole big debate around different
> developer communities as to whether REST needs a contract, except for the
> HTTP protocol, at all. But, the primary intention of this thread is "not"
> to jump into a similar argument :) )
>
> 2. Code first approach, which utilizes implementing the API first and then
> generates Swagger definition to be used for documentation purposes, etc.
>
> Each approach obviously has its own pros and cons. This is, therefore, to
> see what needs to be/already have standardized as the best approach to go
> about API design and implementation.
>
> If we consider contract-first approach, that looks more elegant and lets
> us enable enforcing proper governance across the API design and
> implementation process. For instance, folks can first work on the Swagger
> definition as the contract, at the design phase and then go into the
> implementations later on after verifying the resource definitions, etc. The
> second approach, on the other hand, makes it easier for us to deal with in
> terms of implementing complex and more coarse-grained HTTP APIs (which I
> believe is a common-case in the platform?) and exposing their definitions.
>
> *Impact of this on API documentation*
>
> So, coming back to the topic of documenting APIs with what was discussed
> earlier, if we go by the first approach, there we have the swagger
> definition up-front so we wouldn't need to go for any annotation-based
> models, etc and instead, can directly generate API documentation based on
> the existing Swagger definition via an appropriate doc generator tool.
>
> In contrast, the code-first approach demands us to go for an
> annotation-model or something similar to get the documentation done.
>
> Whichever the case would ultimately produce the same output, but I
> thought, as a platform we need to stick to just one approach and document
> it properly. So the question is, what would that be?
>
>
> Cheers,
> Prabath
> --
> Prabath Abeysekara
> Technical Lead
> WSO2 Inc.
> Email: praba...@wso2.com
> Mobile: +94774171471
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

[Architecture] Data Mapper - xsi:type representation in JSON schema

[Sohani Weerasinghe]

Hi All,

We are in a process of supporting the xsi:type in JSON Schema and please
find the below implementation details.

*Input*:


http://schemas.xmlsoap.org/soap/envelope/;
xmlns:urn="urn:enterprise.soap.sforce.com" xmlns:urn1="urn:
sobject.enterprise.soap.sforce.com" xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance;>
   
  
 QwWsHJyTPW.1pd0_jXlNKOSU
  
   
   
  
   *  *
**
**
*001D00HRzKD*
*Jane*
*Doe*
* *
* *
*Acme Rockets, Inc.*
* *
  
   



*Generated JSON schema via the Data Mapper editor :*

{
   "$schema":"http://json-schema.org/draft-04/schema#;,
   "id":"http://wso2jsonschema.org;,
   "title":"soapenv:Envelope",
   "type":"object",
  * "elementIdentifiers":[  *
*  {  *
* "type":"xsi:type"*
*  }*
*   ],*
   "properties":{
  "soapenv:Body":{
 "id":"http://wso2jsonschema.org/soapenv:Body;,
 "type":"object",
 "properties":{
"urn:create":{
   "id":"http://wso2jsonschema.org/soapenv:Body/urn:create;,
   "type":"object",
   "properties":{
 * "urn:sObjects, xsi:type=urn1:Contact":{  *
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects
",*
* "type":"array",*
* "items":[  *
*{  *
*   "attributes":{  *
*  "xsi:type":{  *
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0/xsi:type
",*
* "type":"string"*
*  }*
*   },*
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0
",*
*   "type":"object",*
*   "value":{  *
*  "type":"string"*
*   },*
*   "properties":{  *
*  "AccountId":{  *
*
 
"id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0/AccountId
",*
* "type":"string"*
*  },*
*  "FirstName":{  *
*
 
"id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0/FirstName
",*
* "type":"string"*
*  },*
*  "LastName":{  *
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0/LastName
",*
* "type":"string"*
*  }*
*   }*
*}*
* ]*
*  },*
 * "urn:sObjects, xsi:type=urn1:Account":{  *
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects
",*
* "type":"array",*
* "items":[  *
*{  *
*   "attributes":{  *
*  "xsi:type":{  *
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0/xsi:type
",*
* "type":"string"*
*  }*
*   },*
*
 "id":"http://wso2jsonschema.org/soapenv:Body/urn:create/urn:sObjects/0
",*
*   "type":"object",*
*   "value":{  *
*  "type":"string"*
*   }*
*}*
* ]*
*  }*
*   }*
*}*
* }*
  },
  "soapenv:Header":{
 "id":"http://wso2jsonschema.org/soapenv:Header;,
 "type":"object",
 "properties":{
"urn:SessionHeader":{
   "id":"
http://wso2jsonschema.org/soapenv:Header/urn:SessionHeader;,
   "type":"object",
   "properties":{
  "urn:sessionId":{
 "id":"
http://wso2jsonschema.org/soapenv:Header/urn:SessionHeader/urn:sessionId;,
 "type":"string"
  }
   }
}
 }
  }
   },
   "namespaces":[
  {
 "prefix":"soapenv",
 

[Architecture] Swagger, API design and related best practices, and docs

[Prabath Abeysekera]

Hi Everyone,

What I'm trying to do primarily is setting up Swagger-based docs for
EMM/IoTS related APIs. However, while I was looking deeper into this, came
across a few things that I need clarifications upon.

*Code-first or Contract-first?*

Right now it appears that there are two approaches being used in the
platform for API design and development.

1. Contract first approach, which utilizes composing the Swagger definition
upfront and then generating the API implementation out of it.

(** I do understand that there's a whole big debate around different
developer communities as to whether REST needs a contract, except for the
HTTP protocol, at all. But, the primary intention of this thread is "not"
to jump into a similar argument :) )

2. Code first approach, which utilizes implementing the API first and then
generates Swagger definition to be used for documentation purposes, etc.

Each approach obviously has its own pros and cons. This is, therefore, to
see what needs to be/already have standardized as the best approach to go
about API design and implementation.

If we consider contract-first approach, that looks more elegant and lets us
enable enforcing proper governance across the API design and implementation
process. For instance, folks can first work on the Swagger definition as
the contract, at the design phase and then go into the implementations
later on after verifying the resource definitions, etc. The second
approach, on the other hand, makes it easier for us to deal with in terms
of implementing complex and more coarse-grained HTTP APIs (which I believe
is a common-case in the platform?) and exposing their definitions.

*Impact of this on API documentation*

So, coming back to the topic of documenting APIs with what was discussed
earlier, if we go by the first approach, there we have the swagger
definition up-front so we wouldn't need to go for any annotation-based
models, etc and instead, can directly generate API documentation based on
the existing Swagger definition via an appropriate doc generator tool.

In contrast, the code-first approach demands us to go for an
annotation-model or something similar to get the documentation done.

Whichever the case would ultimately produce the same output, but I thought,
as a platform we need to stick to just one approach and document it
properly. So the question is, what would that be?


Cheers,
Prabath
-- 
Prabath Abeysekara
Technical Lead
WSO2 Inc.
Email: praba...@wso2.com
Mobile: +94774171471
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Sinthuja Ragendran]

Hi Sumedha,

On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
wrote:

> Geesara,
> This is a model that should be coming out of Dashboard perspective.
>
> If we take a look @ basic building blocks of DS, its (similar to what you
> have mentioned)
> - Gadget
> - Dashboard
> - Wizards
> - Dashboard Admin panel
> - etc
>
> Each of these elements should have a permission model associated per
> instance.
>

Yeah +1, as per now the permission checks are not implemented for these
operations, but we need to incorporate that as well.


> For example, defining "permission to view any gadget" is not enough.  But
> rather it should be "permission to view Gadget X".
> Same should be extended for all other building blocks. (AFAIK, this is not
> there for gadgets as of now)
>
> These need to be stored @ gadget server level and evaluated b4 rendering
> any gadget.
>

Yeah, actually we are planning to implement the role based access control
for gadgets and then again different views of the dashboard page based on
roles.


>
> Permissions to BE
> 
> Once presentation layer permissions are sorted, it becomes responsibility
> of Gadget / Dashboard author to figure out mapping
> those permissions to a backend API.
>
> There are multiple ways to do this based on how backend is secured.
> - Passing session cookie obtained @ login to backend
> - Obtaining a token (OAuth2) using session cooking (using an OAuth2 grant
> type)
> - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
> - IdP enabled deployment
>
> Ensuring backend API's permission requirements match front end user's
> privileges is part of author's
> responsibility. This is not something DS product needs to worry about.
>

Exactly, but I think there should be some API provided by DS server
(shindig features), so that the users can just call the necessary methods
with respective parameters to get oauth token. WDYT?

Thanks,
Sinthuja.


> If by any chance backend is written using WSO2 technologies, we can
> leverage concepts like
> - Sharing same identity provider for both DS and BE server
> - passing authorisation details from FE to BE using JWT/SAML Response /
> User profile
>
>
> Permissions when gadgets being embedded into other products without
> dashboard
> 
> This is yet another perspective of the same problem. This also can be
> solved if we follow same principles
> mentioned above.
> - Having gadget instance level permission definition
> - Way to obtain a gadget by passing in authorisation details (using one of
> the methods mentions above)
>

> Same applies for dashboards.
>
>
> On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap  wrote:
>
>> *Requirement:*
>> *When dashboard retrieving data from some REST APIs which are secured, we
>> do require proper security model in place in order to identify who can
>> access this dashboard and at which level should it be done. In addition,how
>> can dashboard be going to communicate with respective REST API securely?*
>>
>>
>>
>>  Figure 01:
>> Dashboard Server
>>
>>
>> Data providers for gadgets need to communicate with DS securely. Most of
>> the cases data providers are some REST APIs. There might be a situation
>> which dashboard will be getting data from different data providers as well.
>> In the DS perspective, there must be an effective way to tackle these
>> security related issues up to some extent. Referring to figure 1, we are
>> having three places where we can address these issues.
>>
>>- gadget level
>>- per-dashboard level
>>- dashboard server level
>>
>> What would be the proper place which we can address security concerns in
>> a proper manner?  If we try to address this at gadget level, It will be too
>> mush of  granularity which may be preventing the acceptable performance of
>> data retrieval from data providers as well as too mush of load to DS
>> itself.  Also having problems user authentication and authorization at this
>> level as well as per dashboard level. Dashboard server level would be the
>> ideal place which we can address all those  security concerns in a
>> conventional manner. Any advice and suggestions will be greatly appreciated
>> regarding this.
>>
>> Thanks,
>> Geesara,
>>
>> --
>> Geesara Prathap Kulathunga
>> Software Engineer
>> WSO2 Inc; http://wso2.com
>> Mobile : +940772684174
>>
>>
>
>
> --
> /sumedha
> m: +94 773017743
> b :  bit.ly/sumedha
>



-- 
*Sinthuja Rajendran*
Associate Technical Lead
WSO2, Inc.:http://wso2.com

Blog: http://sinthu-rajan.blogspot.com/
Mobile: +94774273955
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Geesara Prathap]

Hi Sumedha,

Thank you very mush for your detailed explanation. I will look into this.

Thanks,
Geesara

On Thu, Apr 28, 2016 at 1:58 PM, Sumedha Rubasinghe 
wrote:

> Geesara,
> This is a model that should be coming out of Dashboard perspective.
>
> If we take a look @ basic building blocks of DS, its (similar to what you
> have mentioned)
> - Gadget
> - Dashboard
> - Wizards
> - Dashboard Admin panel
> - etc
>
> Each of these elements should have a permission model associated per
> instance.
> For example, defining "permission to view any gadget" is not enough.  But
> rather it should be "permission to view Gadget X".
> Same should be extended for all other building blocks. (AFAIK, this is not
> there for gadgets as of now)
>
> These need to be stored @ gadget server level and evaluated b4 rendering
> any gadget.
>
>
> Permissions to BE
> 
> Once presentation layer permissions are sorted, it becomes responsibility
> of Gadget / Dashboard author to figure out mapping
> those permissions to a backend API.
>
> There are multiple ways to do this based on how backend is secured.
> - Passing session cookie obtained @ login to backend
> - Obtaining a token (OAuth2) using session cooking (using an OAuth2 grant
> type)
> - If SSO is enabled, obtaining a token (OAuth2) using SAML Token
> - IdP enabled deployment
>
> Ensuring backend API's permission requirements match front end user's
> privileges is part of author's
> responsibility. This is not something DS product needs to worry about.
>
> If by any chance backend is written using WSO2 technologies, we can
> leverage concepts like
> - Sharing same identity provider for both DS and BE server
> - passing authorisation details from FE to BE using JWT/SAML Response /
> User profile
>
>
> Permissions when gadgets being embedded into other products without
> dashboard
> 
> This is yet another perspective of the same problem. This also can be
> solved if we follow same principles
> mentioned above.
> - Having gadget instance level permission definition
> - Way to obtain a gadget by passing in authorisation details (using one of
> the methods mentions above)
>
> Same applies for dashboards.
>
>
> On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap  wrote:
>
>> *Requirement:*
>> *When dashboard retrieving data from some REST APIs which are secured, we
>> do require proper security model in place in order to identify who can
>> access this dashboard and at which level should it be done. In addition,how
>> can dashboard be going to communicate with respective REST API securely?*
>>
>>
>>
>>  Figure 01:
>> Dashboard Server
>>
>>
>> Data providers for gadgets need to communicate with DS securely. Most of
>> the cases data providers are some REST APIs. There might be a situation
>> which dashboard will be getting data from different data providers as well.
>> In the DS perspective, there must be an effective way to tackle these
>> security related issues up to some extent. Referring to figure 1, we are
>> having three places where we can address these issues.
>>
>>- gadget level
>>- per-dashboard level
>>- dashboard server level
>>
>> What would be the proper place which we can address security concerns in
>> a proper manner?  If we try to address this at gadget level, It will be too
>> mush of  granularity which may be preventing the acceptable performance of
>> data retrieval from data providers as well as too mush of load to DS
>> itself.  Also having problems user authentication and authorization at this
>> level as well as per dashboard level. Dashboard server level would be the
>> ideal place which we can address all those  security concerns in a
>> conventional manner. Any advice and suggestions will be greatly appreciated
>> regarding this.
>>
>> Thanks,
>> Geesara,
>>
>> --
>> Geesara Prathap Kulathunga
>> Software Engineer
>> WSO2 Inc; http://wso2.com
>> Mobile : +940772684174
>>
>>
>
>
> --
> /sumedha
> m: +94 773017743
> b :  bit.ly/sumedha
>



-- 
Geesara Prathap Kulathunga
Software Engineer
WSO2 Inc; http://wso2.com
Mobile : +940772684174
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

[Architecture] [C5] [Hamming] Audit logs in C5.

[Sameera Jayasoma]

Hi All,

Audit logs or Audit trails contain set of log entries which describe a
sequence of actions which have occurred over a time period. From audit
logs, it is possible to trace all the actions of a single user or all the
actions or changes introduced to a certain module in the system etc.  E.g.
It captures all the actions of a single user from the point he logs in to
the application.

In previous versions of the Carbon platform, we only had a logger called
AUDIT and a separate appender which appends audit logs to separate log
file.

The only drawback of this approach is that we don't have a proper way to
capture contextual information. In each and every audit log, we need to
capture logged in user details, IP address of client etc. In the previous
approach developers have to log this information with each and every audit
log attempt. This is suboptimal IMO, we need to implement a mechanism where
developers gives only the log message and system should append all the
other information to the log. I see few ways to implement this.

1) Write a custom appender which write audit logs to the file with
contextual information.
2) Provide API to log audit logs. We can extract contextual information
from the CarbonContext in both of these methods.

Any thoughts.

Thanks,
Sameera.

-- 
Sameera Jayasoma,
Software Architect,

WSO2, Inc. (http://wso2.com)
email: same...@wso2.com
blog: http://blog.sameera.org
twitter: https://twitter.com/sameerajayasoma
flickr: http://www.flickr.com/photos/sameera-jayasoma/collections
Mobile: 0094776364456

Lean . Enterprise . Middleware
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Sumedha Rubasinghe]

Geesara,
This is a model that should be coming out of Dashboard perspective.

If we take a look @ basic building blocks of DS, its (similar to what you
have mentioned)
- Gadget
- Dashboard
- Wizards
- Dashboard Admin panel
- etc

Each of these elements should have a permission model associated per
instance.
For example, defining "permission to view any gadget" is not enough.  But
rather it should be "permission to view Gadget X".
Same should be extended for all other building blocks. (AFAIK, this is not
there for gadgets as of now)

These need to be stored @ gadget server level and evaluated b4 rendering
any gadget.


Permissions to BE

Once presentation layer permissions are sorted, it becomes responsibility
of Gadget / Dashboard author to figure out mapping
those permissions to a backend API.

There are multiple ways to do this based on how backend is secured.
- Passing session cookie obtained @ login to backend
- Obtaining a token (OAuth2) using session cooking (using an OAuth2 grant
type)
- If SSO is enabled, obtaining a token (OAuth2) using SAML Token
- IdP enabled deployment

Ensuring backend API's permission requirements match front end user's
privileges is part of author's
responsibility. This is not something DS product needs to worry about.

If by any chance backend is written using WSO2 technologies, we can
leverage concepts like
- Sharing same identity provider for both DS and BE server
- passing authorisation details from FE to BE using JWT/SAML Response /
User profile


Permissions when gadgets being embedded into other products without
dashboard

This is yet another perspective of the same problem. This also can be
solved if we follow same principles
mentioned above.
- Having gadget instance level permission definition
- Way to obtain a gadget by passing in authorisation details (using one of
the methods mentions above)

Same applies for dashboards.


On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap  wrote:

> *Requirement:*
> *When dashboard retrieving data from some REST APIs which are secured, we
> do require proper security model in place in order to identify who can
> access this dashboard and at which level should it be done. In addition,how
> can dashboard be going to communicate with respective REST API securely?*
>
>
>
>  Figure 01:
> Dashboard Server
>
>
> Data providers for gadgets need to communicate with DS securely. Most of
> the cases data providers are some REST APIs. There might be a situation
> which dashboard will be getting data from different data providers as well.
> In the DS perspective, there must be an effective way to tackle these
> security related issues up to some extent. Referring to figure 1, we are
> having three places where we can address these issues.
>
>- gadget level
>- per-dashboard level
>- dashboard server level
>
> What would be the proper place which we can address security concerns in a
> proper manner?  If we try to address this at gadget level, It will be too
> mush of  granularity which may be preventing the acceptable performance of
> data retrieval from data providers as well as too mush of load to DS
> itself.  Also having problems user authentication and authorization at this
> level as well as per dashboard level. Dashboard server level would be the
> ideal place which we can address all those  security concerns in a
> conventional manner. Any advice and suggestions will be greatly appreciated
> regarding this.
>
> Thanks,
> Geesara,
>
> --
> Geesara Prathap Kulathunga
> Software Engineer
> WSO2 Inc; http://wso2.com
> Mobile : +940772684174
>
>


-- 
/sumedha
m: +94 773017743
b :  bit.ly/sumedha
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] Implementing proper security model for dashboard server

[Srinath Perera]

Since gadgets are deployed as an artifact, shouldn't this information
defined at the Gadget level?

Have we thought about what kind of technologies we will support for
security? for example, maybe we can support data retrieval using an OAuth
token in addition to basic auth over HTTPS.

--Srinath


On Thu, Apr 28, 2016 at 1:00 AM, Geesara Prathap  wrote:

> *Requirement:*
> *When dashboard retrieving data from some REST APIs which are secured, we
> do require proper security model in place in order to identify who can
> access this dashboard and at which level should it be done. In addition,how
> can dashboard be going to communicate with respective REST API securely?*
>
>
>
>  Figure 01:
> Dashboard Server
>
>
> Data providers for gadgets need to communicate with DS securely. Most of
> the cases data providers are some REST APIs. There might be a situation
> which dashboard will be getting data from different data providers as well.
> In the DS perspective, there must be an effective way to tackle these
> security related issues up to some extent. Referring to figure 1, we are
> having three places where we can address these issues.
>
>- gadget level
>- per-dashboard level
>- dashboard server level
>
> What would be the proper place which we can address security concerns in a
> proper manner?  If we try to address this at gadget level, It will be too
> mush of  granularity which may be preventing the acceptable performance of
> data retrieval from data providers as well as too mush of load to DS
> itself.  Also having problems user authentication and authorization at this
> level as well as per dashboard level. Dashboard server level would be the
> ideal place which we can address all those  security concerns in a
> conventional manner. Any advice and suggestions will be greatly appreciated
> regarding this.
>
> Thanks,
> Geesara,
>
> --
> Geesara Prathap Kulathunga
> Software Engineer
> WSO2 Inc; http://wso2.com
> Mobile : +940772684174
>
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>


-- 

Srinath Perera, Ph.D.
   http://people.apache.org/~hemapani/
   http://srinathsview.blogspot.com/
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture