Introduction

Customers of Oracle HCM Cloud extend it by adding custom user interfaces (UI) in web pages or mobile applications.  HCM REST API is vital to enable this ability to extend, by providing fast and simple access to resources in HCM Cloud. An important requirement for access over REST is for employees to get no more access to information over REST API than they are allowed over HCM cloud UI pages.

There can also be uses cases where customers integrate HCM cloud with other 3rd party and Oracle applications using REST API and for this purpose might use users who are not associated with employees. Such system users might be allowed to access all data.

Let's look at how to control access to REST API using a practical example, after a quick review of essential security concepts in HCM cloud application. 

Role-based security in HCM cloud

Role based security is a fundamental concept in fusion cloud applications. It allows enterprises to secure access to data and workflows by the role of an user in the organization and by user's position in a organizational hierarchy, through set of pre-defined or custom roles those are reusable. This a well-documented concept, so I'll not elaborate here further. The graphic below provides and overview and a reference to documentation is provided below.

Figure-Overview of role based security in Oracle HCM Cloud application

Data roles

Job roles, by inhering privileges and duty roles, control what type of data and workflows that a user can access. The next task is to refine control of data access further - for example:

• A HR analyst for a department can only view or update employee information for employees in that department
• A manager can only view information about his or her direct and indirect reports

Data roles, by combing a job role and a security profile, allow restricting access to a slice of a type of information, based on predefined security profiles, or through custom criteria defined by SQL statements.  Data roles can also be enforced over REST API.  This comes handy for use cases such as mobile extensions that depend on access of REST API.

Data roles are not pre-defined out of box, as they are specific to organizations. So they are defined during implementations, under “Assign Security Profiles to Role” task.  

Steps to enable access to HCM REST services

HCM users will not be able to access data over HCM REST API, until a pre-defined REST API Duty role or security privileges granted to such a role are assigned. For example, “Use REST Service - Worker Details Read Only” is a pre-defined HCM Duty role that allows access to view worker details.  In summary, here are the steps to enable data security over HCM REST API.

1. Create a Custom job role or modify existing job role with a pre-defined HCM REST Duty role
2. Create a custom security profile, if necessary, to define custom data access (or pick a pre-defined security profile)
3. Using the job role and security profile from previous steps, create a data role. 
4. Assign data role to a user to enable data access

At this point, the user is ready to access the desired information over REST API.

Data security example

Figure - a sample employee hierarchy 

In the sample hierarchy of employees shown above, let's look at 3 REST API use cases.

• Use case 1.Lindsey Jacona can only view her own information
• Use case 2.Kerry Lane can only view his and all of his direct and indirect reports' information
• Use case 3.Raymond Harazin can view information about employees under two managers, Sharon Colby and Matthew Schnieder.

The common task for all 3 use cases is to define a job role (or modify an existing job role) that includes duty role "Use REST Service - Worker Details Read Only". Once the job role is available, next step is to define data role and grant the data role to the user.

For use case 1, define a data role that includes the job role and the person security profile "View Own Record". This data role restricts the access to one's own information.

For use case 2, define a data role that includes the job role and the person security profile "View Manager Hierarchy".  This data role restricts access to one's direct and indirect reports in the hierarchy. 

For use case 3, a custom security profile is required. This security profile includes the "View All Workers" person security profile and a custom SQL snippet that restricts the list of workers to those report to managers Sharon Colby and Matthew Schnieder. Here is one working example SQL:

EXISTS( SELECT 1 
  FROM "FUSION"."PER_ASSIGNMENT_SUPERVISORS_F" "PER_ASSIGNMENT_SUPERVISORS_F"
  WHERE  "PER_ASSIGNMENT_SUPERVISORS_F"."MANAGER_ID" IN ({insert SQL to select person ids})
  AND "PER_ASSIGNMENT_SUPERVISORS_F"."PERSON_ID"=&table_alias.person_id  )

Most use cases are covered by one of the pre-defined security profiles. Use caution while defining custom profiles as the SQL queries can adversely affect application performance. 

References

HCM Cloud security: https://docs.oracle.com/en/cloud/saas/applications-common/18b/ochus/an-introduction-to-hcm-security-in-the-cloud.html