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 : [email protected]
Mobile : +94779367571
Web : https://wso2.com/
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
