Infisical Organizational Structure Blueprint

Infisical is designed to provide comprehensive, centralized, and efficient management of secrets, certificates, and encryption keys within organizations. Below is an overview of Infisical's structured components, which developers and administrators can leverage for optimal project management and security posture.

0. Cluster/Instance

• Best Practice: In most cases, a single Infisical instance or cluster is sufficient. Multiple clusters are typically only necessary for large, globally distributed organizations.
• Use Cases:
  • Cloud-hosted deployments typically use a single cluster. While technically possible, using multiple clusters is not a common practice and is generally unnecessary.
  • Self-hosted deployments can be configured with multiple clusters if needed.

1. Organization

• Definition: An Infisical organization is a set of projects that use the same billing.
• Use Cases:
  • In self-hosted setups, you can create multiple organizations (e.g., one for each department or business unit).
  • In cloud-hosted deployments, it's standard to use a single organization.

1.5 Sub-Organizations (Enterprise)

• Definition: Sub-organizations are optional child organizations within a root organization, enabling large enterprises to create autonomous units that operate independently while inheriting common resources from the parent organization.
• Hierarchy: One level of nesting is supported (root organization to sub-organizations). Each sub-organization works like a regular organization with its own projects, groups, and machine identities.
• Resource Sharing: Users, groups, and machine identities from the root organization can be pulled into sub-organizations. Resources flow downward only and must be explicitly added to a sub-organization before use.
• Project Ownership: Projects belong to the organization you're in. In a sub-organization, you only see projects for that sub-organization—not root organization projects.
• Limitations: Authentication (SSO, SCIM, LDAP) and billing are configured at the root organization level only. No default sub-organization exists—they are created when needed.

For detailed information on resource inheritance, project ownership, and enterprise examples, see the Sub-Organizations documentation.

2. Projects

• Definition and Role: Projects are the highest-level construct within an organization in Infisical. They serve as the primary container for all functionalities.
• Common Project Mappings: Projects typically align with applications, services, or code repositories — each being a valid and common approach depending on your organizational structure.
• Functional Capabilities: Each project encompasses features for managing secrets, certificates, and encryption keys, serving as the central hub for these resources.

<Note>Projects are isolated from one another. Secrets, certificates, and other resources cannot be shared or referenced across different projects. Each project maintains its own separate set of resources.</Note>

3. Environments

• Purpose: Environments are designed for organizing and compartmentalizing secrets within projects.
• Customization Options: Environments can be tailored to align with existing infrastructure setups of any project. Default options include Development, Staging, and Production.
• Structure: Each environment inherently has a root level for storing secrets, and additional hierarchical layers can be created through folders for better secret management.

4. Folders

• Use Case: Folders are available for more advanced organizational needs, allowing logical separation of secrets.
• Typical Structure: Folders can correspond to specific logical units, such as microservices or different layers of an application, providing refined control over secrets.

5. Imports

• Purpose and Benefits: To promote reusability and avoid redundancy within a project, Infisical supports the use of imports and references. This allows secrets, folders, or entire environments to be referenced within the same project as needed.
• Project Isolation: Imports and references only work within a single project. Secrets cannot be imported or referenced across different projects, as projects are isolated from one another.
• Best Practice: Utilizing secret imports or references ensures consistency and minimizes manual overhead when managing secrets within a project.

6. Approval Workflows

• Importance: Implementing approval workflows is recommended for organizations aiming to enhance efficiency and strengthen their security posture.
• Types of Workflows:
  • Access Requests: This workflow allows developers to request access to sensitive resources. Such access can be configured for temporary use, a practice known as "just-in-time" access.
  • Change Requests: Facilitates reviews and approvals when changes are proposed for sensitive environments or specific folders, ensuring proper oversight.

7. Access Controls

Infisical’s access control framework is unified for both human users and machine identities, ensuring consistent management across the board.

7.1 Roles

• 2 Role Types:
  • Organization-Level Roles: Provide broad access across the organization (e.g., ability to manage billing, configure settings, etc.).
  • Project-Level Roles: Essential for configuring access to specific secrets and other sensitive assets within a project.
• Granular Permissions: While default roles are available, custom roles can be created for more tailored access controls.
• Admin Considerations: Note that admin users are able to access all projects. This role should be assigned judiciously to prevent unintended overreach.

<Note>Project access is defined not via an organization-level role, but rather through specific project memberships of both human and machine identities. Admin roles bypass this by default. </Note>

7.2 Additional Privileges

Additional privileges can be assigned to users and machines on an ad-hoc basis for specific scenarios where roles alone are insufficient. If you find yourself using additional privileges too much, it is recommended to create custom roles. Additional privileges can be temporary or permanent.

7.3 Attribute-Based Access Control (ABAC)

Attribute-based Access Controls allow restrictions based on tags or attributes linked to secrets. These can be integrated with SAML assertions and other security frameworks for dynamic access management.

7.4 User Groups

• Application: Organizations should use users groups in situations when they have a lot of developers with the same level of access (e.g., separated by team, department, seniority, etc.).
• Synchronization: User groups can be synced with an identity provider to maintain consistency and reduce manual management.

Implementation Note

For larger-scale organizations, automating configurations through Terraform or other infrastructure-as-code (IaC) tools is advisable. Manual configurations may lead to errors, so leveraging IaC enhances reliability and consistency in managing Infisical's robust capabilities.

This structured approach ensures that Infisical's functionalities are fully leveraged, providing both flexibility and rigorous control over an organization's sensitive information and access needs.