Hi all,
According to the recent discussions we've had, we have modified the initial
DB design as follows.
- Remove the FK constraint on SCOPE_ID, as it would be easy when
decoupling API-M from IS components in the future.
- Add a UUID for Global Scopes to support REST APIs
AM_GLOBAL_SCOPE
SCOPE_ID INTEGER NOT NULL,
TENANT_ID INTEGER DEFAULT -1,
UUID VARCHAR (256)
In addition, the following points are highlighted which we need to
discuss further.
- The management of scopes can be done in the Publisher Portal and it
would make more sense if move it to the same UI view of APIs as scopes are
straightly attached to APIs.
- With the above design of global scopes, there will be no way to
differentiate global and local scopes from the swagger. Hence, if the
global scope - role bindings are updated after publishing the API, the role
changes will not be reflected when validating API requests using Basic
Auth. In such cases, we need to republish the APIs.
- Currently, we do not support adding local scopes with the same name
for different APIs. Hence, other than using local scopes to restrict the
use of the same for other APIs, there would not be any difference between
local and global scopes.
- If we are removing local scope support, we need to migrate the
existing local scopes of previous versions to global. In migration, we need
to add the existing scope_ids and tenant_ids to the AM_GLOBAL_SCOPE table
with new UUIDs.
Thanks
*Dushani Wellappili*
Senior Software Engineer - WSO2
Email : dusha...@wso2.com
Mobile : +94779367571
Web : https://wso2.com/
On Mon, Jan 20, 2020 at 11:19 AM Dushani Wellappili <dusha...@wso2.com>
wrote:
> Hi all,
>
> This is to provide an example use-case of supporting global scopes when an
> application is using multiple APIs and it supports functionalities for
> users with different types of permissions. There are two sets of users
> where the one set will only have view-only permissions and another set will
> have both read and edit permissions.
>
> For example, assume an application is using both API A and B. API A has 2
> operations ( /a GET, /a POST) and similarly API B has 2 operations ( /b
> GET, /b POST). The users of set 1 only have read permission and set 2 have
> both read-write permissions. The permissions are given by assigning roles.
>
> set 1 user - role 1 (read-only role)
> set 2 users - role 2 (read-write role)
>
> The users of set 1 need to be provided access for both (/a GET) and (/b
> GET). The users of set 2 need to be provided access for all the 4
> operations (/a GET, /a POST, /b GET, /b POST) of API A and API B.
>
> With the current functionality of WSO2 API-M local scopes, this can be
> achieved by creating 2 local scopes (view-scope, edit-scope) for each API,
> and define role bindings of the users based on the permissions they
> have. Then, assign them to the API operations.
>
> *API A*
> view-scopeA - role1, role2
> edit-scopeA - role2
>
> /a GET view-scopeA
> /a POST edit-scopeA
>
> *API B*
> view-scopeB - role1, role2
> edit-scopeB - role2
>
> /b GET view-scopeB
> /b POST edit-scopeB
>
> The main limitation of the above way is that we need to create 4 scopes
> separately with 4 unique scope keys duplicating the scope-role bindings.
> Hence, for such cases, it is ideal to have the capability to define the
> scope-role bindings globally and reuse them in the API operations. So the
> API developers can restrict access for the API operations of the APIs
> globally.
>
> So there will be only two scopes which needs to be created globally.
> view-scope - role1, role2
> edit-scope - role2
>
> *API A*
> /a GET view-scope
> /a POST edit-scope
>
> *API B*
> /b GET view-scope
> /b POST edit-scope
>
> In addition to the above, if there will be later requirement where there
> is another set of users with a different set of permissions (role3) and
> they need to be given permission to use (/b GET) operation of API B. If so,
> with the above design where we do not support multiple scopes per resource,
> we need to create another new scope with all role1, role2, and role3
> bindings. Then assign it for (/b GET) instead of edit-scope. In that case,
> the point of reusing global scopes across multiple APIs would not become
> beneficial. Hence, by supporting multiple scopes per resource, we can keep
> the above design as it is and separately create a global/local scope with
> bindings for role3 and attach it to (/b GET) operation.
>
> new-scope - role3
>
> *API B*
> /b GET view-scope, new-scope
> /b POST edit-scope
>
>
>
> *Dushani Wellappili*
> Senior Software Engineer - WSO2
>
> Email : dusha...@wso2.com
> Mobile : +94779367571
> Web : https://wso2.com/
>
>
>
>
> On Thu, Jan 16, 2020 at 10:18 PM Dushani Wellappili <dusha...@wso2.com>
> wrote:
>
>> The delete operation should be corrected as follows.
>>
>> #-----------------------------------------------------
>>
>> # Delete the global scope
>>
>> #-----------------------------------------------------
>>
>> delete:
>>
>> security:
>>
>> - OAuth2Security:
>>
>> - apim:global_scope_manage
>>
>> summary: Delete a global scope
>>
>> description: |
>>
>> This operation can be used to delete an existing Global Scope
>> proving the Id of the scope.
>>
>> parameters:
>>
>> - $ref: '#/parameters/scopeId
>>
>> responses:
>>
>> 200:
>>
>> description: |
>>
>> OK.
>>
>> Resource successfully deleted.
>>
>> 404:
>>
>> description: |
>>
>> Not Found.
>>
>> The resource to be deleted does not exist.
>>
>> schema:
>>
>> $ref: '#/definitions/Error'
>>
>>
>>
>> *Dushani Wellappili*
>> Senior Software Engineer - WSO2
>>
>> Email : dusha...@wso2.com
>> Mobile : +94779367571
>> Web : https://wso2.com/
>>
>>
>>
>>
>> On Thu, Jan 16, 2020 at 3:33 PM Dushani Wellappili <dusha...@wso2.com>
>> wrote:
>>
>>> Hi all,
>>>
>>> - Global OAuth2 Scopes are useful when an organization/department (a
>>> tenant) has a need to globally control the fined grained access control
>>> permissions of all the published APIs, from a central place.
>>> - It reduces the rework of creating the same scope with duplicate
>>> access control permissions for each of the API. With this, such scope
>>> creation would be a one time task. Global scopes will be created by
>>> administrative users and the API developers can attach the available
>>> global
>>> scopes for the API resources when designing the API.
>>> - The support to add multiple OAuth scopes per resource is useful
>>> when you need to group the access permissions to resources by scopes and
>>> reuse them across different APIs.
>>>
>>> *DESIGN*
>>>
>>> - The global scope management view will be added to the Publisher UI
>>> so that the API developers can easily check what are the available global
>>> scopes and their role bindings from the same portal when creating an API.
>>> - Current Publisher Portal UI for Resource Management of an API will
>>> be modified to attach the global scopes and attach multiple scopes per
>>> resource.
>>> - The current flow of managing and attaching per API scopes will
>>> remain as it is.
>>> - To make sure that only privileged users(admins) can
>>> add/update/delete any global scope, the relevant Publisher REST APIs will
>>> be secured using a REST API scope. Eg: apim:global_scope_manage
>>> - To support global scopes, we need to add a new table
>>> AM_GLOBAL_SCOPE on AM_DB.
>>>
>>> *AM_GLOBAL_SCOPE*
>>> SCOPE_ID INTEGER NOT NULL,
>>> TENANT_ID INTEGER DEFAULT -1,
>>> FOREIGN KEY (SCOPE_ID) REFERENCES IDN_OAUTH2_SCOPE (SCOPE_ID) ON
>>> DELETE CASCADE
>>>
>>>
>>> - We need to modify the PK constraint on IDN_OAUTH2_RESOURCE_SCOPE
>>> to be a composite key on both RESOURCE_PATH and SCOPE_ID to support
>>> multiple scopes per resource.
>>>
>>>
>>> *IDN_OAUTH2_RESOURCE_SCOPE *
>>> RESOURCE_PATH VARCHAR(255) NOT NULL,
>>> SCOPE_ID INTEGER NOT NULL,
>>> TENANT_ID INTEGER DEFAULT -1,
>>> PRIMARY KEY (SCOPE_ID, RESOURCE_PATH),
>>> FOREIGN KEY (SCOPE_ID) REFERENCES IDN_OAUTH2_SCOPE (SCOPE_ID) ON
>>> DELETE CASCADE
>>>
>>>
>>> - JDBCScopeValidator will be modified to support validating multiple
>>> scopes attached per resource.
>>> - Global Scopes will be added via the following Publisher REST APIs.
>>> Using resource name "global-scopes" seems more appropriate since these
>>> REST
>>> APIs will be used to only manage global scopes. The "Scope" resource and
>>> "ScopeList" resource are already defined in Publisher REST API, hence we
>>> can use the same resources for global-scopes as well.
>>>
>>>
>>> ######################################################
>>>
>>> # The "Global Scopes" resource APIs
>>>
>>> ######################################################
>>>
>>> /global-scopes
>>>
>>>
>>> #-------------------------------------------------------------
>>>
>>> # Retrieve the global scopes list
>>>
>>> #-------------------------------------------------------------
>>>
>>> get:
>>>
>>> security:
>>>
>>> - OAuth2Security:
>>>
>>> - apim:api_view
>>>
>>> summary: Get the list of global scopes
>>>
>>> responses:
>>>
>>> 200:
>>>
>>> description: |
>>>
>>> OK.
>>>
>>> Global Scope list is returned.
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/ScopeList'
>>>
>>> headers:
>>>
>>> Content-Type:
>>>
>>> description: |
>>>
>>> The content type of the body.
>>>
>>> type: string
>>>
>>> 500:
>>>
>>> description: Internal server error while retrieving global
>>> scope list
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Error'
>>>
>>>
>>> #-------------------------------------------------------------
>>>
>>> # Create a new global scope
>>>
>>> #-------------------------------------------------------------
>>>
>>> post:
>>> security:
>>> - OAuth2Security:
>>> - apim:global_scope_manage
>>> summary: Add a new global scope
>>> description: |
>>> This operation can be used to add a new global scope.
>>> parameters:
>>> - in: body
>>> name: body
>>> description: |
>>> Scope object that needs to be added
>>> required: true
>>> schema:
>>> $ref: '#/definitions/Scope'
>>> responses:
>>> 201:
>>> description: |
>>> Created.
>>> Successful response with the newly created Scope object as
>>> an entity in the body.
>>> schema:
>>> $ref: '#/definitions/Scope'
>>> headers:
>>> Content-Type:
>>> description: |
>>> The content type of the body.
>>> type: string
>>> 400:
>>> description: |
>>> Bad Request.
>>> Invalid request or validation error
>>> schema:
>>> $ref: '#/definitions/Error'
>>> 415:
>>> description: |
>>> Unsupported media type.
>>> The entity of the request was in a not supported format.
>>>
>>>
>>> ######################################################
>>>
>>> # The "Individual Global Scope" resource APIs
>>>
>>> ######################################################
>>>
>>> /global-scopes/{scopeId}
>>>
>>>
>>> #-------------------------------------------------------------
>>>
>>> # Retrieve the details of a global scope
>>>
>>> #-------------------------------------------------------------
>>>
>>>
>>> get:
>>>
>>> security:
>>>
>>> - OAuth2Security:
>>>
>>> - apim:api_view
>>>
>>> summary: Get details of a global scope
>>>
>>> parameters:
>>> - $ref: '#/parameters/scopeId'
>>>
>>> responses:
>>>
>>> 200:
>>>
>>> description: |
>>>
>>> OK.
>>>
>>> Requested Global Scope is returned.
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Scope'
>>>
>>> headers:
>>>
>>> Content-Type:
>>>
>>> description: |
>>>
>>> The content type of the body.
>>>
>>> type: string
>>>
>>> 404:
>>> description: |
>>> Not Found.
>>> Requested Global Scope does not exist.
>>> schema:
>>> $ref: '#/definitions/Error'
>>>
>>>
>>> #-------------------------------------------------------------
>>>
>>> # Update a global scope
>>>
>>> #-------------------------------------------------------------
>>>
>>> put:
>>>
>>> security:
>>>
>>> - OAuth2Security:
>>>
>>> - apim:global_scope_manage
>>>
>>> summary: Update an API
>>>
>>> description: |
>>>
>>> This operation can be used to update an existing Global Scope.
>>>
>>> parameters:
>>>
>>> - $ref: '#/parameters/scopeId'
>>>
>>> - in: body
>>>
>>> name: body
>>>
>>> description: |
>>>
>>> Scope object that needs to be updated
>>>
>>> required: true
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Scope'
>>>
>>> responses:
>>>
>>> 200:
>>>
>>> description: |
>>>
>>> OK.
>>>
>>> Successful response with updated Scope object
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Scope'
>>>
>>> headers:
>>>
>>> Content-Type:
>>>
>>> description: |
>>>
>>> The content type of the body.
>>>
>>> type: string
>>>
>>> 400:
>>>
>>> description: |
>>>
>>> Bad Request.
>>>
>>> Invalid request or validation error
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Error'
>>>
>>> 404:
>>>
>>> description: |
>>>
>>> Not Found.
>>>
>>> The resource to be updated does not exist.
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Error'
>>>
>>>
>>> #-----------------------------------------------------
>>>
>>> # Delete the definition of an API
>>>
>>> #-----------------------------------------------------
>>>
>>> delete:
>>>
>>> security:
>>>
>>> - OAuth2Security:
>>>
>>> - apim:global_scope_manage
>>>
>>> summary: Delete an API
>>>
>>> description: |
>>>
>>> This operation can be used to delete an existing Global Scope
>>> proving the Id of the scope.
>>>
>>> parameters:
>>>
>>> - $ref: '#/parameters/scopeId
>>>
>>> responses:
>>>
>>> 200:
>>>
>>> description: |
>>>
>>> OK.
>>>
>>> Resource successfully deleted.
>>>
>>> 404:
>>>
>>> description: |
>>>
>>> Not Found.
>>>
>>> Resource to be deleted does not exist.
>>>
>>> schema:
>>>
>>> $ref: '#/definitions/Error'
>>>
>>> *FLOW*
>>>
>>> 1. A privileged user/administrative user logs into Publisher Portal and
>>> creates a global scope providing name, description and role bindings.
>>> 2. Upon checking whether the scope key is not duplicated in the
>>> IDN_OAUTH2_SCOPE table, this scope will be added to the IDN_OAUTH2_SCOPE,
>>> IDN_OAUTH2_SCOPE2_BINDING and AM_GLOBAL_SCOPE tables.
>>> 3. An API developer creates an API and visits the resources page. The
>>> list of scopes to add per resource is populated using the per-API scopes
>>> from the API object and from the "GET /global-scopes" backend service call.
>>> 4. The developer selects a set of global/per-API scopes for the
>>> resource. The swagger is updated with the scopes list and resource scope
>>> list. The backend service "PUT apis/{apiId}/swagger" updates the
>>> IDN_OAUTH2_RESOURCE_SCOPE and AM_API_SCOPES table.
>>> 5. App Developer will generate a token with the scopes and invoke the
>>> API. During the KeyValidation service, when the scopes are validated for
>>> the resource using the JDBCScopeValidator, it will check whether token
>>> bears any of the given resource scopes.
>>>
>>> This is a draft design for the implementation. Hence appreciate your
>>> suggestions/comments to improve the above. Once the above is finalized, we
>>> will work on the UI design.
>>>
>>> Thanks
>>>
>>> *Dushani Wellappili*
>>> Senior Software Engineer - WSO2
>>>
>>> Email : dusha...@wso2.com
>>> Mobile : +94779367571
>>> Web : https://wso2.com/
>>>
>>>
>>>
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
