Organization-based access control

Overview

Unity customers require controls to govern access to individual data records and resources (such as campaigns etc). Record access control is crucial for compliance, and it should be applicable both when viewing data within the application and when exporting it. Resource access control is essential for maintaining user boundaries, ensuring that users only see resources relevant to them, and hiding resources belonging to other teams.

The governance of such access control is facilitated by Organization-Based Access Control (OBAC) in Unity.

Concept

Organization-Based Access Control (OBAC) relies on labels, which represent relevant distinctions in your business operations, such as different geographic areas, business units, or brands.

Organizations and data records are assigned labels, and
Users and resources are assigned to organizations.

The organizations linked with a particular user or resource determine the records they can access. A record becomes available to a user if it includes all the labels from at least one of the user’s organizations. In other words, the organization's labels must be a subset of the record’s labels.

In the example above, the Record possesses all labels associated with Organization 1, making it accessible to Organization 1’s users. However, since it lacks all the labels for Organizations 2 and 3, it is not available to members of those organizations.

Record Access Example

In the examples below, consider the following labels: Germany, France, Marketing, Advertising, BrandA, and BrandB. Using these labels, we establish the organizations Germany, Germany Marketing, France, France BrandA, France BrandB, and BrandB, and then assign them to users Alice, Bob, Carl, and Diane.

Organization	Labels
Germany	Germany
Germany Marketing	Germany, Marketing
France	France
France BrandA	France, BrandA
France BrandB	France, BrandB
BrandB	BrandB

User	Organizations
Alice	Germany, BrandB
Bob	Germany Marketing
Carl	France BrandA, France BrandB
Diane	Germany, France

Records	Labels
R1	Germany, Marketing, BrandA
R2	Germany, BrandB
R3	France, Marketing, Advertising
R4	France

Alice is a member of the organizations Germany and BrandB. She will have access to R1 and R2 because each contains the label Germany. However, she will not have access to R3 or R4 since neither contains the labels Germany or BrandB.

Bob is a member of the organization Germany Marketing. He will have access to R1 because its labels include both Germany and Marketing. However, he will not have access to R2, R3, or R4 because none of them have both labels.

Carl is a member of France BrandA and France BrandB. He will not have access to any of the records because none of them contain both France and BrandA or France and BrandB.

Diane is a member of the organizations Germany and France. She will have access to all of the records because each of them contains either Germany or France.

Resource Access Example

When Unity users create a resource, such as a campaign or export job, it is automatically assigned to all their organizations by default (If OBAC is enabled and user is assigned Organizations). If the user is a member of multiple organizations, they have the option to remove some of them, provided that at least one organization remains associated with the resource.

The organizations assigned to the resource dictate which records it will retrieve when executed, following the same logic as user access. Moreover, the organizations linked with a resource determine which other users have the ability to access it.

Assuming the same labels, organizations, and users as mentioned above, consider the following campaigns: [Include the details of the campaigns here.]

Campaign	Organizations
C1	France, Germany Marketing
C2	Germany
C3	France BrandA, France BrandB
C4	Germany, France

When executed, C1 will provide records containing both the label France and the label Marketing. C2 will retrieve records containing the label Germany. C3 will deliver records containing either the label France and the label BrandA or both the label France and the label BrandB. C4 will deliver records containing either the label Germany or the label France. Additionally, if standard enforcement is selected, all campaigns will deliver records with no labels. (Refer to "Enabling Enforcement" for a discussion of enforcement options.)

Regarding access to the campaigns, Alice, a member of the organizations Germany and BrandB, will have manage access to C2 and view access to C4 since she is a member of all or one of their respective organizations. She will have no access to C1 or C3.

Bob, a member of the organization Germany Marketing, will not have access to any of the campaigns since none of them are assigned to his organization.

Carl, a member of France BrandA and France BrandB, will have manage access to C3 because he is a member of both its organizations. However, he will not have access to C1, C2, or C4.

Diane, a member of the organizations Germany and France, will have manage access to C2 and C4 since she is a member of all the organizations assigned to each. She will not have access to C1 or C3.

Another example for OBAC

Organization	Labels	Users	Organizations	Record ID	Labels	Campaign ID	Organizations
US Sales	US, Sales	Alice	US Sales, Canada Electronics	R1	US, Sales, Electronics	C1	US Sales, Canada Electronics
Canada Electronics	Canada, Electronics	Bob	Europe Marketing	R2	Canada, Electronics, Apparel	C2	Europe Marketing
Europe Marketing	Europe, Marketing	Carl	Asia HomeGoods, Global HR	R3	Europe, Marketing, Apparel	C3	Asia HomeGoods, Global HR
Asia HomeGoods	Asia, HomeGoods	Diane	US Sales, Europe Marketing	R4	Asia, HomeGoods	C4	US Sales, Europe Marketing
Global HR	HR			R5	HR

	User Access to Records	User Access to Resources
Alice (Organizations: US Sales, Canada Electronics)	R1: Yes, matches US, Sales (subset of labels) R2: Yes, matches Canada, Electronics R3: No R4: No R5: No	C1: Manage, matches both organizations C2: No C3: No C4: View, matches at least one organization (US Sales)
Bob (Organization: Europe Marketing)	R1: No R2: No R3: Yes, matches Europe, Marketing R4: No R5: No	C1: No C2: Manage, matches Europe Marketing C3: No C4: View, matches at least one organization (Europe Marketing)
Carl (Organizations: Asia HomeGoods, Global HR)	R1: No R2: No R3: No R4: Yes, matches Asia, HomeGoods R5: Yes, matches HR	C1: No C2: No C3: Manage, matches both organizations C4: No
Diane (Organizations: US Sales, Europe Marketing)	R1: Yes, matches US, Sales. R2: No R3: Yes, matches Europe, Marketing. R4: No R5: No	C1: View, matches at least one organization (US Sales) C2: Manage, matches Europe Marketing C3: No C4: Manage, matches both organizations

All Access Organization

In addition to any custom organizations you create, there is a default organization called "All Access" with the following privileges:

Unrestricted Record Access:
Members can access all records, regardless of their labels and enforcement settings.
Manage Resource Access:
- Members can manage access to all resources.
- They can choose to assign a resource to:
  - No organization
    - Resources assigned to this are available to everyone but manageable only by "All Access" members
    - The records they retrieve depend on enforcement settings:
      - Standard enforcement: Shows only records with no labels
      - Strict enforcement: Shows no records at all
  - All Access organization
    - Resources assigned to this are available only to members of the "All Access" organization
    - These resources give access to all records regardless of their labels and enforcement settings.
  - Specific other organizations.

Resource Access Summary

Although resource access restrictions may seem complex, they follow three simple principles:

All Access Privileges: Members of the "All Access" organization have unrestricted access to all resources and records.
Visibility and Management:
- Resources are visible to users who belong to at least one of their organizations.
- Resources can only be managed by users who belong to all their assigned organizations.
Assignment Limits: Users can assign resources only to organizations they are part of.

The tables below provide a summary of scenarios for the "view," "copy," and "manage" cases.

View/Start/Stop Access

User Assigned to	Resource has All Access	Resource has Organization 1	Resource Assigned to Organization 2	Resource Assigned to Organization 1 & Organization 2	Resource Assigned No Organization
All Access	x	x	X	X	x
Organization 1		x		X	x
Organization 2			X	x	x
Organization 1 & Organization 2		x	X	x	x
No Organization					x

Copy Access

User Assigned to	Resource has All Access	Resource has Organization 1	Resource has Organization 2	Resource has Organization 1 & Organization 2	Resource has No organization
All Access	x	x	x	x	x
Organization 1		x		x	x
Organization 2			x	x	x
Organization 1 & Organization 2		x	x	x	x
No Organization

Create/Edit/Delete Access

User Assigned to	Resource has All Access	Resource has Organization 1	Resource has Organization 2	Resource has Organization 1 & Organization 2	Resource has No organization
All Access	x	x	x	x	x
Organization 1		x
Organization 2			x
Organization 1 & Organization 2		x	x	x
No Organization

Implementing OBAC

Step 1: Identifying Organizations and Labels

When implementing OBAC, the first step is to identify the organizations that are appropriate for your users. Best Practice: Start with the minimum number of organizations needed and expand only as necessary.

After defining the organizations, determine the labels required to map records to each organization. Depending on your use case:

You may create a single label for each organization.
Alternatively, you can use a combination of labels (e.g., a label for the country and another for the brand).

OBAC enforcement acts as a filter applied to specific data objects. To restrict access to an object:

Add an attribute with the array of strings data type to the object.
Populate the array with the appropriate labels.

When the object is accessed, records are filtered to ensure users or resources see only what they are authorized to access.
Best Practice: Apply enforcement to as few objects as possible to simplify label management and minimize performance impact.

Labels are used to map data records for OBAC enforcement.

Step 2: Creating Labels

To create labels, follow these steps:

Navigate to the Admin section of Oracle Unity.
Click on the Organizations tab.
Select the Labels & Categories section.

Only users with the Instance Admin or Governance User role can access this screen.

Creating a Category

Click Create Category.
Enter a category name (up to 128 characters).
- Names can be in any language.
- Special characters such as !@#%^&*()+|:<>?=;',./ are not allowed.
- The name cannot begin with a space.

Modifying or Deleting Categories

To rename a category, click the three dots at the end of its row.
Deletion is allowed only if the category has no associated labels.
Category names must be unique.

Creating a Label

Click Add Label.
Enter a label name (up to 20 characters).
- Allowed characters: a-z, A-Z, 0-9, and _.
- Case Sensitivity: Label names must match the labels in data records exactly (e.g., "Germany" is not equivalent to "germany" or "GERMANY").

Modifying or Deleting Labels

To modify a label’s description or delete a label, click the three dots at the end of its row.
Labels cannot be modified once created.
Deletion is only possible if the label is not used in any organization.
Label names must be unique, even across different categories.

Step 3: Creating Organizations

After creating your categories and labels, the next step is to use these labels to define organizations.

Navigate to the Organizations section under the Organizations tab.
Click the Create Organization button.

Assigning Labels to an Organization

The initial step in creating an organization is selecting the labels you want to assign to it:

You can choose one label from each category, with a maximum of five labels in total.
When multiple labels are selected, "AND" logic is applied.
- For example, if the organization has labels Germany and Advertising, it will have access to records containing both labels.
- However, if a record has only Germany or only Advertising, members of the organization will not have access to it.

Naming the Organization

By default, a name is automatically generated for your organization by combining the selected labels. You can modify this name if needed.

Organization names can be up to 128 characters long.
Names can be in any language but cannot contain special characters such as !@#%^&*()+|:<>?=;',./.
The first character of the name cannot be a space.

Limits:

You can create up to 200 organizations.
Each organization must have a unique name and a unique combination of labels.

Modifying or Deleting Organizations

To modify an organization, click the three dots at the end of its row.
- You can update the organization’s name or description at any time.
- Labels cannot be changed once assigned.
Deletion is only possible if the organization is not assigned to any user or resource.

In addition to the organizations you create, there is a default organization called "All Access."

Members of this organization have unrestricted access to all records and resources.
While it is common to assign this organization to users with the Instance Admin role, this assignment is not automatic and must be done explicitly.

Step 4: Assigning Organizations to Users

After creating your organizations, you can assign them to users.

Navigate to the Users tab in the Admin section.
Locate the user you want to assign an organization to.
Click the three dots at the end of the row containing the user’s name.

Assignment Guidelines:

A user can be assigned to either the All Access organization or up to ten other organizations.
Unlike roles, users are not automatically assigned to any organization by default.

Step 5: Labeling Records

OBAC is enforced on an object-by-object basis. The first step is to determine which objects require OBAC enforcement. This decision depends on your business and legal requirements for controlling access to customer data, as well as how your tenant is configured.

Deciding Where to Enforce OBAC

While it may seem initially beneficial to enforce OBAC on every data object, the recommended best practice is to apply it only to data objects where it is strictly necessary.

The first reason for minimizing the number of data objects subject to OBAC is the practical consideration of maintaining labels on numerous objects as customer data evolves in the real world. The more mappings there are, the greater the potential for errors.

The second reason is performance-related. Each time a query is executed, the system checks whether the involved data objects are configured to enforce OBAC. If they are, the system filters out any records that are not accessible for the user/resource. The more objects being filtered, the longer this process will take.

Lastly, enforcement on multiple data objects can impact outputs in ways that may not be immediately apparent. For example, consider two Customer records, 1234 and 5678, with different label assignments. If these records are merged into a MasterCustomer record (1234) with a promotion rule of type "Union," the MasterCustomer record receives both labels.

While it may seem beneficial to enforce OBAC on every data object, the recommended best practice is to apply it only to data objects where it is strictly necessary.

Reasons to Minimize OBAC Enforcement:

Maintenance Complexity:
- Managing labels across numerous objects becomes increasingly complex as customer data changes in real time.
- More mappings increase the likelihood of errors.
System Performance:
- Each time a query is executed, the system checks if the objects involved are configured for OBAC.
- Filtering records for OBAC enforcement increases query processing time, especially if applied to multiple objects.
Unexpected Data Outputs:
- OBAC enforcement on multiple objects can produce unintuitive results.
- For instance, consider the following scenario:
  - Assume Customer records 1234 and 5678 have different label assignments but are merged into MasterCustomer record 1234.
  - The label promotion rule is set to "Union", meaning the MasterCustomer record inherits both labels: {France, Marketing}.

Master Customer		Customer			Order Item
ID	Labels	ID	Name	Labels	Customer ID	Product
1234	{France, Marketing	1234	Bob	{France}	1234	Backpack
		5678	Robert	{Marketing}	5678	Tent

Case 1: Amy (Organization: France)

Amy belongs to the organization France, with access to records labeled France.
Amy creates a campaign with the France organization targeting customers who purchased a tent.

If OBAC is enabled only on MasterCustomer:
- Amy has access to MasterCustomer record 1234, which links to Customer record 5678 and its associated order item, Tent.
- Result: MasterCustomer record 1234 qualifies for Amy’s campaign.
If OBAC is enabled on both MasterCustomer and Customer:
- Amy has access to MasterCustomer record 1234 but not Customer record 5678, as the label Marketing is required.
- Result: MasterCustomer record 1234 does not qualify for Amy’s campaign.
  
  Case 2: Brian (Organizations: France and Marketing)
- Brian belongs to the organizations France and Marketing, with access to records labeled with either label.
If OBAC is enabled only on MasterCustomer:
- Brian has access to MasterCustomer record 1234, which links to Customer record 5678 and its associated order item, Tent.
- Result: MasterCustomer record 1234 qualifies for Brian’s campaign.
- Brian creates a campaign with the France and Marketing organizations targeting customers who purchased a tent.
If OBAC is enabled on both MasterCustomer and Customer:
- Brian has access to MasterCustomer record 1234 and Customer record 5678, which links to the order item, Tent.
- Result: MasterCustomer record 1234 qualifies for Brian’s campaign.

If enforcing OBAC on certain objects (e.g., Customer) produces unintended restrictions, it may indicate a need to reevaluate merging records with differing labels. In such cases, you may need to update deduplication rules to prevent label conflicts. By carefully considering these factors, you can determine the most effective and efficient way to enforce OBAC in your system.

Configuring Data Objects

Once you have determined that OBAC should be enforced on a specific object, follow these steps to configure it:

Step 1: Create an Attribute for Labels

Navigate to the Data Model page.
Select the object you want to configure.
Click the "+" button in the upper-right corner of the page to create a new attribute.
Assign an appropriate Name and ID to the attribute.
Set the Data Type to "array – string".
At the bottom of the configuration form, check the box indicating that this attribute will be used to enforce OBAC.
- Important: Only one attribute per data object should be designated for OBAC enforcement.

Step 2: Enable OBAC Enforcement on the Data Object

Locate the object you want to enforce OBAC on in the Data Model.
Click the three dots next to the object’s name and select “Edit”.
Under Advanced Options, check the box labeled “Enforce organization-based access control”.

Note: There is a current UI limitation with the enforcement checkbox:

The checkbox to enable OBAC enforcement does not appear when creating the attribute.
As a workaround, first create the attribute, then select "Edit" for the object to enable the checkbox.

Configuring Ingest Jobs

Labels can only be added to a record at the time of ingestion. There is no mechanism to retroactively apply labels to data already present in Unity. Additionally, each record is limited to a maximum of 40 labels.

Adding Labels via API

For data ingested via the API, labels must be included in the payload. Below are examples:

Adding Multiple Labels as an Array:

{ "customers": [ 
	{ "SourceID": "Infinity",
	"SourceCustomerID": "123458", 
	"Labels": ["Sales", "Germany"] } 
	] 
}

Adding a Single Label as a String:

{ "customers": [ 
	{ "SourceID": "Infinity",
	"SourceCustomerID": "123458",
	"Labels": "Sales" } 
	] 
}

Note: Sending a single value as a string will overwrite any existing labels for that record.

Adding Labels via Ingest Jobs

For data ingested via Ingest Jobs, there are two methods for specifying labels:

Include Labels Directly in the CSV File:

In this method, all labels are provided as a list within the CSV file. Use square brackets ([]) when there is no value to ensure proper formatting.

Example CSV File:
```
SourceID,SourceCustomerID,Labels
OFF001,C1234,"[""France""]" 
OFF001,C1235,"[""France"",""Marketing""]" 
OFF001,C1236,"[]" 
OFF001,C1237,"[""Germany"",""Marketing""]"
```
Use the "Append Array" Transformation Rule:
If you include labels as strings in the ingest file, you can use the “append array” transformation rule to populate the array-of-strings attribute for the labels.

Note: Ensure that the total number of labels per record does not exceed 40.

Configuring Clustering and Promotion Rules

To enforce OBAC on master entities, you need to update your clustering and promotion rules based on your business requirements. Depending on your needs, you may choose to:

Block records with different labels from being merged.
Promote labels from all input records to maximize accessibility.

Both approaches are supported and can be configured accordingly.

Blocking the Merging of Records with Different Labels

If your business requires records with different labels not to be merged, update your clustering rules as follows:

Include a 100% match requirement on the attribute that contains the labels.
This requirement must be added to each clustering rule for the relevant data objects.

When labels are always identical, you can configure your promotion rules to promote any record's label as the master record's label.

Deduplication rules to prevent merging of records with different labels.

Promoting All Input Labels

If your business prioritizes maximizing the number of organizations that can access a data record, you can take the opposite approach:

Do not modify the deduplication rules, allowing records with different labels to be merged.
Add a promotion rule with the merge type set to “Union”.

This configuration ensures that the master record combines all labels from the input records. For example:

If one input record has the label France and another has the label Marketing, the resulting master record will have both labels (France and Marketing)

Step 6: Enabling Enforcement

After completing the configuration and ingesting data labels, the final step is to enable OBAC enforcement. Follow these steps:

Navigate to the Settings Section
In the Organizations tab, go to the Settings section.
Toggle Enforcement
- Use the toggle switch to turn on enforcement.
- Select one of the following enforcement modes:
  - Standard Enforcement: Records with no labels will be accessible to all users.
  - Strict Enforcement: Records with no labels will be accessible only to members of the All Access organization.

Note: When enabling OBAC, you must click on the white square inside the toggle button—not the surrounding gray background—for the toggle to activate.

Once OBAC is enabled:

Segmentation Canvas Filters: Filters for OBAC labels will appear on the Segmentation canvas.
Access Sections: New sections will appear on the Campaign, Export, and Intelligence Workbench screens, enabling access control based on OBAC.
Publish Required: You must publish the configuration for enforcement to apply to job runs.

Using OBAC

Segments

Segments are not directly assigned to organizations. Instead, each user’s counts and segment previews are filtered according to the organizations they belong to.
Default Counts: On the segmentation canvas, the default count reflects records accessible to at least one of the user’s organizations.
Custom Counts: Users can refine counts for specific organizations by clicking the ∑ symbol, selecting the organizations, and clicking Refresh. The segment sample records will also adjust to the selected organizations.
All Access Members: Users in the All Access organization see counts and samples for all records, regardless of labels (even under strict enforcement). They can still filter counts and samples for up to 10 organizations via the popup.
Users Without Organizations:
- Standard Enforcement: They see only records with no labels.
- Strict Enforcement: They see no records, and their counts will be zero.

Segment Delivery and Export Jobs

Users only see Segment Delivery and Export Jobs that are:
- Assigned to at least one of their organizations
- Not assigned to any organization
All Access Members: They see all segment delivery/export jobs, regardless of label assignments.
View-Only Access: Users with view-only permissions can see segment delivery/export job details, but the Save options are disabled.
Creating/Editing:
- All Access Members can assign segment delivery or export jobs to:
  - No organization.
  - The All Access organization.
  - One or more other organizations

Intelligence Workbench

Recommendation: When OBAC is enabled, it’s advisable to assign the All Access organization to models so that all records are consistently scored.
Mutually Exclusive Labels: If business requirements prevent using a single model for all records, ensure the labels applied to data objects are mutually exclusive.
- This ensures no record falls under multiple models, avoiding inconsistent scores due to conflicting outputs.

When OBAC is being enforced, models should either apply to all records or ensure records are mutually exclusive to avoid scoring conflicts.

Data Viewer

With OBAC enabled, the Data Viewer screen automatically filters records based on the user’s organizations.
All Access Requirement: Only members of the All Access organization can view all records.

Profile Explorer

Update the DSV and IDGraph Rules to support label filtering -

DSV Configuration (`metadata/datasourceviews/IDGraph_Customer`):

Add the Labels attribute to the outputAttributes section for both the data object and query as a whole:

{
  "outputAttributes": [
    {
      "atype": ".ReferenceAttribute",
      "tableName": "c1",
      "attributeName": "Labels"
    }
  ]
}

IDGraph Rules (metadata/idgraphrules/customer360):

Add the Labels attribute as the lbacIdentifier for enforcing OBAC

{
  "lbacIdentifier": {
    "atype": ".DSVAttribute",
    "dsvId": "Customer_DSV",
    "attributeName": "Labels"
  }
}

Limitations

Eloqua integration

For data activation in Eloqua:

The user who installed the Oracle Unity app in Eloqua must be a member of the All Access organization.

This is necessary to ensure the user has access to all records, regardless of labels