> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/govern/secure-your-data/intents/intents-reference-guide.md). # Intents Reference Guide Learn how intents enforce access controls {% hint style="info" %} **Public preview**: This feature is being released incrementally to customers on a rolling basis. If the feature is not available in your tenant yet, contact your Immuta representative to enable it. {% endhint %} Intents is a feature that enforces permissions based on the user's specific intent, allowing policy authors to scope data access to specific reasons for accessing data. Instead of basing access decisions solely on who users are, intents allow the policy decision to be based on what the users are doing and why they need access. An intent is a form of identity that governors create using the user attributes and groups registered in Immuta: * **Intent name**: The intent name will be included in the role or group Immuta creates in your data platform. * **Group name**: Assigning a group name to an intent authorizes members of the group to assume the intent. Any user-specific attributes for members of that group are removed and replaced by the attributes associated with the intent when they assume the intent. Governors can assign multiple groups to an intent, and a role or group will be created for each intent-group pair. See the [section below for details](#what-does-immuta-do-in-my-environment). * **Intent attributes**: The access these attributes provide will be associated with the intent. Because the attributes of the users within the groups assigned to the intent may not be consistent, once the user assumes the role or group Immuta creates for the intent in the data platform, these intent attributes will replace any attributes directly assigned to the user. Members of the groups assigned to an intent [can assume that intent in their native platform](#what-does-immuta-do-in-my-environment). Once the intent is assumed, the intent attributes replace any user attributes assigned to that user. In the illustration below, if Member 1 assumed the `Fraud detection` intent, their `Clearance:Secret` attribute would be replaced by the `Exception:InternalData` intent attribute.

For instructions on creating or managing an intent, see the [Manage intents guide](/saas/govern/secure-your-data/intents/manage-intents.md). ## What does Immuta do in my environment? Immuta generates a role or group in your data platform for each intent-group pair that is created in Immuta. In the example below, a governor creates a Clinical trial intent and assigns the group `Analysts` to it. Then, Immuta generates a Clinical trial intent group in Databricks that members of the group `Analysts` can assume to query data under that intent.

Once an intent is deleted in Immuta, that role or group is removed from the data platform. The Immuta-generated roles or groups can be viewed on the intent page. See the [Assume an intent guide](/saas/govern/secure-your-data/data-consumers/assume-an-intent.md#assume-the-immuta-generated-role) for details. ### Databricks group naming convention The name of the group Immuta creates in Databricks includes the intent name and the group name assigned to the intent. The naming convention of the group differs slightly depending on whether the group name matches the intent name. * **Group name differs from intent name**: The group created by Immuta includes an Immuta prefix, the intent name, and the group name assigned to the intent. For example, if an intent called `Fraud detection` had the group `Analysts` assigned to it, the name of the group Immuta creates in Databricks would follow the pattern below. * Naming convention: `excl--intent--` * Example: `excl-immuta_123456789_unitycatalogconnection-intent-Fraud detection-Analysts` * **Group name matches intent name**: The group created by Immuta includes an Immuta prefix and the intent name. For example, if an intent called `Analysts` had the group `Analysts` assigned to it, the name of the group Immuta creates in Databricks would follow the pattern below. * Naming convention: `excl--intent-` * Example: `excl-immuta_123456789_unitycatalogconnection-intent-Analysts` The Immuta-generated groups can be viewed on the intent page. See the [Assume an intent guide](/saas/govern/secure-your-data/data-consumers/assume-an-intent.md#assume-the-immuta-generated-role) for details. ### Policy enforcement with intents Once a user [assumes an intent](/saas/govern/secure-your-data/data-consumers/assume-an-intent.md) in their data platform, the following events occur: 1. Group names carry over: The `Analysts` group stays the same for the group member who assumes the `Clinical trial` intent in the diagram below. 2. The intent attributes replace the user’s birthright attributes: `Access:Clinical trial` replaces any other attributes associated with the user assuming the `Clinical trial` intent. 3. The policy on the data source checks the facts about the user: * Group: `Analysts` * Attribute: `Access:Clinical trial` 4. The `Analysts` group member who assumes the intent in Databricks is granted access to the Clinical trial data.

Once the user closes that intent context in their native platform, the facts about the user revert to their birthright attributes, and so they would not have access to Clinical trial data. ## Supported policies * [Grant and guardrail subscription policies](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies.md): Groups and attributes of an intent can be used in both subscription policy types. * [Protect and reveal data policies](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/data-policies.md): The groups and attributes in an intent can be used in all data policies. ## Policy authoring strategy Because birthright attributes are replaced by intent attributes, you must consider how you want access to be enforced when authoring policies: * If you want access to stay the same (despite the intent): Groups should determine access. * If you want access to change: Attributes should determine access Use the following examples as a guide to design intents and author policies.

Keep table access; gain masking exceptions

### **Scenario: I want a group to retain their table access but see data unmasked when working under a specific intent.** Users in the group `Analyst` have access to tables tagged `Research analysis`, but some of the restricted data is masked for them. When accessing this data for a fraud detection project, these users should be able to see restricted data unmasked. **How to design the intent** 1. Create the **Fraud detection** intent. 2. Assign the `Analyst` group to the intent. 3. Assign attributes to the intent that will replace the users' birthright attributes and allow an exception to data tagged `Restricted`. For example, `Exception:Restricted`.


Analyst group	Attribute: `Department:Research`
Intent: Fraud detection	Assigned group: `Analyst` Attribute: `Exception:Restricted`

**How to design the policies** 1. Author a **subscription policy** that uses the **group name**: Grant users in group `Analyst` access to tables tagged `Research analysis`. \ Use the group name in a subscription policy to dictate table access so that when they assume the intent, their group access remains unchanged and they will retain their existing access to tables. 2. Author a **data policy** that uses the **intent attribute**: Mask columns tagged `Restricted` except when user possesses an attribute with key `Exception` that matches any column tag. \ Use the intent attribute in a data policy to dictate the masking exception. When they assume this intent, the users' birthright attributes will be replaced by the intent attributes and they will gain masking exceptions. #### **Subscription policy illustration: Reference group name to keep access** The table below illustrates how the following policy enforces access controls for 3 different users: > Grant users in group `Analyst` access to tables tagged `Research analysis`


	Research table `Research analysis`	Employee table (no data source tags)	Customer table `Research analysis`	Marketing table `Research analysis`
User A Intent: Fraud detection Intent group: `Analyst` Intent attribute: `Exception:Restricted`	✅	❌	✅	✅
User B Intent: None Group: `Analyst` Attribute: `Location:Maryland`	✅	❌	✅	✅
User C Intent: None Group: `HR`	❌	✅	❌	❌

In this example, * **User A** assumes the **Fraud detection** intent and keeps access to tables tagged `Research analysis` because they are a member of the `Analyst` group. * **User B** has access to tables tagged `Research analysis` because they are a member of the `Analyst` group, even though they **did not assume** the **Fraud detection** intent. * **User C** is denied access to tables tagged `Research analysis` because they are not a member of the `Analyst` group. #### **Data policy illustration: Reference intent attributes to gain masking exceptions** The table below illustrates how the following policy enforces access controls for 2 different users: > Mask columns tagged `Restricted` except when user possesses an attribute with key `Exception` that matches any column tag.

name column email column wage office location

name column
Restricted email column
Restricted wage column
(no column tags) office location column
Location

User A

Intent: Fraud detection
- Intent group: Analyst
- Intent attribute: Exception:Restricted

✅

User B

Intent: None
Group Analyst
Attribute: Location:Maryland

❌

✅

In this example, * **User A** **assumes** the **Fraud detection** intent and their birthright attributes are replaced by the intent attribute `Exception:Restricted`, so they see the columns tagged `Restricted` unmasked. * **User B** **does not assume** the **Fraud detection** intent, so they do not have the attribute `Exception:Restricted` and the `Restricted` columns are masked.

Gain table access; keep masking exceptions

### **Scenario: I want a group to gain access to more tables but keep their masking exceptions when working under an intent.** Users in the group `Analyst` have access to tables tagged `Research analysis`, but to complete the Fraud detection project, they need access to customer, marketing, and employee data. The users in this group already have a masking exception for columns tagged `Restricted`, and they should keep this masking exception. **How to design the intent** 1. Create the **Fraud detection** intent. 2. Assign the `Analyst` group to the intent. 3. Assign attributes to the intent that will grant access to the additional tables: `Exception:Marketing`, `Exception:Employee`, `Exception:Customers`


Analyst group	Attribute: `Department:Research`
Intent: Fraud detection	Assigned group: `Analyst` Attributes: `Exception:Employee`, `Exception:Customers`, `Exception:Marketing`

**How to design the policies** 1. Author a **subscription policy** that uses the **group name**: Grant users in group `Analyst` access to data sources tagged `Research analysis`. \ Use the group name in a subscription policy to dictate table access so that when they assume the intent, their group access remains unchanged and they will retain their existing access to tables. 2. Author a **subscription policy** that uses the **intent attribute**: Grant users with attribute value in `Exception` that matches any data source tag. \ Use the intent attribute in a subscription policy to dictate access to additional tables so that when they assume the intent, their birthright attributes are replaced by the intent attributes and they can gain access to tables. 3. Author a **data policy** that uses the **group name**: Mask data tagged `Restricted` except for users in group `Analyst`. \ Use the group name in a data policy to dictate a masking exception so that when they assume the intent, their group access remains unchanged and they will retain their masking exceptions. #### **Subscription policy illustration: Reference group name and intent attributes to gain access** The table below illustrates how the following policies enforce access controls for 3 different users: > * Grant users in group `Analyst` access to tables tagged `Research analysis`. > * [Grant users access when @hasTagAsAttribute('Exception', 'dataSource')](#user-content-fn-1)[^1]


	Research table `Research analysis`	Employee table `Employee`	Customer table `Customers`	Marketing table `Marketing`
User A Intent: Fraud detection Intent group: `Analyst` Intent attribute: `Exception:Employee`, `Exception:Customers`, `Exception:Marketing`	✅	✅	✅	✅
User B Intent: None Group: `Analyst` Attribute: `Location:Maryland`	✅	❌	❌	❌
User C Intent: None Group: `HR` Attribute: `Exception:Employee`	❌	✅	❌	❌

In this example, * **User A** **assumes** the **Fraud detection** intent and keeps access to tables tagged `Research analysis` because they are a member of the `Analyst` group. This user also gains access to tables tagged `Employee`, `Customers`, and `Marketing` because those tags match the attribute value of the intent attributes. * **User B** has access to tables tagged `Research analysis` because they are a member of the `Analyst` group, even though they **did not** **assume** the **Fraud detection** intent. However, they do not gain access to tables tagged `Employee`, `Customers`, and `Marketing` because their birthright attribute `Location:Maryland` does not match those tags. * **User C** is denied access to tables tagged `Research analysis` because they are not a member of the `Analyst` group. This user only has access to the table tagged `Employee` because their birthright attribute `Exception:Employee` matches that table tag. #### **Data policy illustration: Reference group name to keep masking exceptions** The table below illustrates how the following policy enforces access controls for 3 different users: > Mask columns tagged `Restricted` except for users in group `Analyst`.

	name column	email column	wage	office location
	name column `Restricted`	email column `Restricted`	wage column (no column tags)	office location column `Location`
User A Intent: Fraud detection Intent group: `Analyst` Intent attribute: `Exception:Employee`, `Exception:Customers`, `Exception:Marketing`	✅	✅	✅	✅
User B Intent: None Group `Analyst` Attribute: `Location:Maryland`	✅	✅	✅	✅
User C Intent: None Group: `HR` Attribute: `Exception:Employee`	❌	❌	✅	✅

In this example, * **User A** **assumes** the **Fraud detection** intent and can see masked columns tagged `Restricted` in the clear because they are a member of the `Analyst` group. * **User B** can see masked columns tagged `Restricted` in the clear because they are a member of the `Analyst` group, even though they **did not** **assume** the **Fraud detection** intent. * **User C** cannot see columns tagged `Restricted` because they are not a member of the `Analyst` group.

Limit table access; gain masking exceptions

### **Scenario: I want to limit what tables a group has access to** **but see data unmasked when working under a specific intent.** Users in the group `Analyst` have access to tables tagged `Research analysis`, but when working on their current project their access should be limited to tables specific to the clinical trial they're working on. When accessing this clinical trial data, these users should be able to see restricted data unmasked. **How to design the intent** 1. Create the **Clinical trial** intent. 2. Assign the `Analyst` group to the intent. 3. Assign an attribute to the intent that grants access to a specific table. For example, `ClinicalTrial:Trial A`. 4. Assign an attribute to the intent that allows a masking exception to columns tagged `Restricted`. For example, `Exception:Restricted`


Analyst group	Attribute: `Department:Research`
Intent: Clinical trial	Assigned group: `Analyst` Attributes: `ClinicalTrial:Trial A`, `Exception:Restricted`

**How to design the policies** 1. Author a **subscription policy** that uses the **intent attribute**: Grant users with attribute `ClinicalTrial` with value that matches any data source tag.\ \ Use the intent attribute in a subscription policy to dictate access to tables so that when they assume the intent, their birthright attributes are replaced by the intent attributes and their access to tables is limited. 2. Author a **data policy** that uses the **intent attribute**: Mask columns tagged `Restricted` except when user possesses an attribute with key `ClinicalTrial` that matches any column tag.\ \ Use the intent attribute in a data policy to dictate the masking exception. When they assume this intent, the users' birthright attributes will be replaced by the intent attributes and they will gain masking exceptions. #### **Subscription policy illustration: Reference intent attributes to limit access** The table below illustrates how the following policy enforces access controls for 3 different users: > [Grant users access when @hasTagAsAttribute('ClinicalTrial', 'dataSource')](#user-content-fn-2)[^2]


	Research table `Research analysis`	Patient data `Trial A`	Clinical Trial A `Trial A`	Clinical Trial B `Trial B`
User A Intent: Clinical trial Intent group: `Analyst` Intent attributes: `ClinicalTrial:Trial A`, `Exception:Restricted`	❌	✅	✅	❌
User B Intent: None Group: `Analyst` Attribute: `Location:Maryland`	✅	❌	❌	❌
User C Intent: None Group: `HR`	❌	❌	❌	❌

In this example, * **User A** **assumes** the **Clinical trial** intent and their access is limited to tables tagged `Trial A` because those tags match the attribute value of the intent attribute `ClinicalTrial:Trial A`. * **User B** has access to tables tagged `Research analysis` because they are a member of the `Analyst` group. However, they do not have access to tables tagged `Trial A` or `Trial B` because they **did not assume** the **Clinical trial** intent, so they do not have the `ClinicalTrial` attribute. * **User C** is denied access to tables tagged `Research analysis` because they are not a member of the `Analyst` group. They also do not have access to tables tagged `Trial A` or `Trial B` because they do not have the `ClinicalTrial` attribute. #### **Data policy: Reference intent attributes to gain masking exceptions** The table below illustrates how the following policy enforces access controls for 2 different users: > Mask columns tagged `Restricted` except when user possesses an attribute with key `Exception` that matches any column tag.

name column email column wage office location

name column
Restricted, Trial A email column
Restricted, Trial A wage column
(no column tags) office location column
Location

	name column	email column	wage	office location
	name column `Restricted`, `Trial A`	email column `Restricted`, `Trial A`	wage column (no column tags)	office location column `Location`
User A Intent: Clinical trial Intent group: `Analyst` Intent attributes: `ClinicalTrial:Trial A`, `Exception:Restricted`	✅	✅	✅	✅
User B Intent: None Group `Analyst` Attribute: `Location:Maryland`	❌	❌	✅	✅

User A

Intent: Clinical trial
- Intent group: Analyst
- Intent attributes: ClinicalTrial:Trial A, Exception:Restricted

✅

User B

Intent: None
Group Analyst
Attribute: Location:Maryland

❌

✅

In this example, * **User A** **assumes** the **Clinical trial** intent and their birthright attributes are replaced by the intent attribute `Exception:Restricted`, so they see the columns tagged `Restricted` unmasked. * **User B** **does not assume** the **Clinical trial** intent, so they do not have the attribute `Exception:Restricted` and the `Restricted` columns are masked.

## Masked joins When users assume an intent, masked columns (using hashing) can be joined for data sources to which those users have access when acting under that intent. * **Without an intent**: When users access data outside an intent, Immuta uses a unique salt for hashing per table when masking a column to break referential integrity and ensure the masked values aren’t able to join to avoid toxic combinations — a goal of masking. * **With an intent**: Once a user assumes an intent, Immuta uses a consistent salt across all data sources that user can access under that intent, which returns referential integrity and allows users to join on two masked columns as long as hashing is used as the masking type, since the point of that intent is to use that data together. ## Limitation **Databricks groups per account**: Databricks has a limit of 250,000 groups for Databricks customers using Account SCIM 2.1. All other Databricks environments are subject to a 5,000 group limit. [^1]: Grants users access when the attribute `Exception` has a value that matches a data source tag. [^2]: Grants users access when the attribute `ClinicalTrial` has a value that matches a data source tag. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/saas/govern/secure-your-data/intents/intents-reference-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.