mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
118 lines
5.1 KiB
Plaintext
118 lines
5.1 KiB
Plaintext
---
|
||
title: "Attribute-based Access Controls"
|
||
description: "Learn how to use ABAC to manage permissions based on identity attributes."
|
||
---
|
||
|
||
Infisical's Attribute-based Access Controls (ABAC) allow for dynamic, attribute-driven permissions for both user and machine identities.
|
||
ABAC policies use metadata attributes—stored as key-value pairs on identities—to enforce fine-grained permissions that are context aware.
|
||
|
||
In ABAC, access controls are defined using metadata attributes, such as location or department, which can be set directly on user or machine identities.
|
||
During policy execution, these attributes are evaluated, and determine whether said actor can access the requested resource or perform the requested operation.
|
||
|
||
## Project-level Permissions
|
||
|
||
Attribute-based access controls are currently available for polices defined on projects. You can set ABAC permissions to control access to environments, folders, secrets, and secret tags.
|
||
|
||
### Setting Metadata on Identities
|
||
|
||
<Tabs>
|
||
<Tab title="Manually Configure Metadata">
|
||
<Steps>
|
||
<Step title="Navigate to the Access Control page on the organization sidebar and select an identity (user or machine).">
|
||
<img src="/images/platform/access-controls/add-metadata-step1.png" />
|
||
</Step>
|
||
<Step title="On the Identity Page, click the pencil icon to edit the selected identity.">
|
||
<img src="/images/platform/access-controls/add-metadata-step2.png" />
|
||
</Step>
|
||
<Step title="Add metadata via key-value pairs and update the identity.">
|
||
<img src="/images/platform/access-controls/add-metadata-step3.png" />
|
||
</Step>
|
||
</Steps>
|
||
</Tab>
|
||
<Tab title="Automatically Populate Metadata">
|
||
For organizations using SAML for login, Infisical automatically maps
|
||
metadata attributes from SAML assertions to user identities. This makes it
|
||
easy to create policies that dynamically adapt based on the SAML user’s
|
||
attributes.
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Defining ABAC Policies
|
||
|
||
<img src="/images/platform/access-controls/example-abac-1.png" />
|
||
|
||
ABAC policies make use of identity metadata to define dynamic permissions. Each attribute must start and end with double curly-brackets `{{ <attribute-name> }}`.
|
||
The following attributes are available within project permissions:
|
||
|
||
- **User ID**: `{{ identity.id }}`
|
||
- **Username**: `{{ identity.username }}`
|
||
- **Metadata Attributes**: `{{ identity.metadata.<metadata-key-name> }}`
|
||
|
||
During policy execution, these placeholders are replaced by their actual values prior to evaluation.
|
||
|
||
## Access Attributes from Machine Identity Login
|
||
|
||
When authenticating with machine identity providers like OIDC, your login process may include additional attributes or claims that can be used for making permission decisions.
|
||
These attributes can be mapped to your access control policies to provide fine-grained, attribute-based access control (ABAC).
|
||
|
||
### Using OIDC Authentication Attributes
|
||
|
||
After authenticating via OIDC, you can access the claims provided by your identity provider and use them in permission decisions:
|
||
|
||
1. Navigate to the Identity Authentication settings and select the OIDC Auth Method.
|
||
2. In the **Advanced section**, find the Claim Mapping configuration.
|
||
3. Map the OIDC claims to permission attributes by specifying:
|
||
|
||
- **Attribute Name**: The name that will be used in your permission policies
|
||
- **Claim Path**: The dot notation path to the claim in the OIDC token (e.g., user.department)
|
||
|
||
<img src="/images/platform/access-controls/abac-policies-by-auth.png" />
|
||
|
||
For example, if your OIDC provider returns claims like
|
||
|
||
```json
|
||
{
|
||
"sub": "user123",
|
||
"name": "Jane Doe",
|
||
"user": {
|
||
"department": "engineering",
|
||
"role": "developer"
|
||
}
|
||
}
|
||
```
|
||
|
||
You could create mappings like:
|
||
|
||
- Attribute Name: **department**, Claim Path: **user.department**
|
||
- Attribute Name: **user_role**, Claim Path: **user.role**
|
||
|
||
Once configured, these attributes will be included in the access token after login and can be referenced in permission policies:
|
||
|
||
<img src="/images/platform/access-controls/abac-policy-oidc-format.png" />
|
||
|
||
<Info>
|
||
Currently, only OIDC authentication is supported. Support for Kubernetes and
|
||
other authentication methods is planned for future releases.{" "}
|
||
</Info>
|
||
|
||
### OIDC Authentication
|
||
|
||
- **OIDC Bound Claims**: `{{ identity.auth.oidc.claims.<permission claim name> }}`
|
||
|
||
### Example Use Case
|
||
|
||
#### Location-based Access Control
|
||
|
||
Suppose you want to restrict access to secrets within a specific folder based on a user's geographic region.
|
||
You could assign a `location` attribute to each user (e.g., `identity.metadata.location`).
|
||
You could then structure your folders to align with this attribute and define permissions accordingly.
|
||
|
||
For example, a policy might restrict access to folders matching the user's location attribute in the following pattern:
|
||
|
||
```
|
||
/appA/{{ identity.metadata.location }}
|
||
```
|
||
|
||
Using this structure, users can only access folders that correspond to their configured `location` attribute.
|
||
Consequently, if a users attribute changes due to relocation, no policies need to be changed to gain access to the folders associated with their new location.
|