How-To: Platform Roles in WSO2 Identity Server
Fine-grained Authorization for Platform Resources
Introduction
A permission in IAM is defined as, a combination of a resource and one of its corresponding actions. Permissions are a fundamental element of any authorization decision.
For an overview of the permission levels that are supported by WSO2 Identity Server, and the various use cases around permissions in WSO2 Identity Server, refer my article “Permissions with WSO2 Identity Server” [1].
Platform Roles
The WSO2 Identity Server comes with native multi-tenancy capability which allows it to be deployed as SaaS solution in your enterprise. An IAM SaaS solution is commonly known as an ‘Identity-as-a-Service’ (IDaaS).
The direct consumers of the IDaaS become the tenants of that IDaaS platform. Each tenant gets to manage its own users, groups, organisations, roles and permissions. However, there may be some applications which are meant to be used by all the tenants. They are commonly known as ‘platform applications’. These applications are typically provided by the vendor of the IDaaS platform or by the enterprise that is hosting the IDaaS solution. For example, the ‘User Portal’ that comes with WSO2 Identity Server from version 5.9.0 onwards is a platform application. Similarly the ‘Identity Console’ that comes comes with version 5.11.0 as a beta release is another platform application.
Platform application authorization is generally governed using ‘platform roles’. Platform roles are roles that are defined across all the tenants of an IDaaS. That means that they represent the same set of permissions under any tenant. The platform roles may not be modified by a tenant, but tenants can manage the assignments of users, groups and organisations of the respective tenant to these platform roles for authorization in the platform applications.
As of the latest version of WSO2 Identity Server it doesn’t have the capability to define platform roles. Therefore as a workaround how it needs to be done is duplicate and manage the platform roles in each tenant in the platform. Similarly the permissions that need to be assigned to these platform roles also need to be duplicated inside each tenant in the platform. However, duplicating the tenant level permissions into every new tenant that is getting created in the WSO2 Identity Server is an available functionality. Following the nomenclature of platform roles, these permissions can be called ‘platform permissions’.
Manage Custom Platform Roles and Platform Permissions
Following steps will let you create custom platform permissions via the management console UI.
1. Go to the Registry Browser in the management console.
2. Expand the browser and navigate to “/_system/governance/permission”. This is the path of the registry where all the permissions are managed in WSO2.
3. Platform permissions are tenant level permissions. Therefore we need to create platform permissions under the “/_system/governance/permission/admin” collection. Click on this node.
4. Click on “Add Collection” to add the root platform permission.
5. Enter a name for the root platform permission you are going to create. E.g. “platform”. Enter a description for the root platform permission you are going to create. E.g. “This is the root collection of all the platform permissions”.
6. Click ‘Add’ to add this collection under the “admin” permission collection.
7. Click on the new created root platform permissions and navigate into it.
8. Expand the ‘Properties’ tab.
9. Click on ‘Add New Property’.
10. For the ‘Name’ field enter the value as “name”, and for the ‘Value’ field enter the value which is going to appear as the permission display name in the permission tree.
11. Click on ‘Add’.
12. After completing the above steps you could navigate to the permission listing of any role and view the permissions tree. You should be able to find the newly added root permission now in the permission tree.
Similarly you can manage addition child permissions under the root permission as you wish.
If you wish to achieve the same using a SOAP API, you can use the Registry SOAP API whose WSDL is hosted at the following URL in the WSO2 Identity Server distribution:
https://{IP}:{Port}/services/WSRegistryService.wsdlYou can refer documentation in [2] and [3] to learn more about how this admin SOAP service can be invoked from a SOAP client.
The same functionality above can be achieved using the Registry Rest API [4] as well. However, the Rest API is not shipped with the vanilla WSO2 Identity Server. You will need to copy the war file [4] into the following web application deployment folder of the Identity Server distribution:
<WSO2_IS_HOME>/repository/deployment/server/webappsOnce platform permissions are created the creation of platform roles will follow the same process of creating Roles in WSO2 Identity Server. The creation of platform roles can also be automated through tenant creation listeners.
Managing Role Entitlements
Once the platform permissions are created, the role entitlements can be managed using the Roles API [5] that is introduced from WSO2 Identity Server v5.11.0 onwards.
Summary
In this article I have explained what are platform permissions, the significance of platform permissions in an IDaaS solution, and how to efficiently manage platform permissions in WSO2 Identity Server, as of its latest release at the time of this writing.
References
[1] https://medium.com/@johann_nallathamby/permissions-with-wso2-identity-server-e6f80376548f
[2] https://docs.wso2.com/display/Governance540/WS-API+Sample
[3] https://is.docs.wso2.com/en/latest/develop/calling-admin-services/
[5] https://is.docs.wso2.com/en/latest/develop/scim2-rest-apis/#/Roles%20Endpoint
