Skip to main content

Managing Access to Projects

Business Objective: Rapid Onboarding with Accountability & Scalable Team Management​

This guide teaches you how to achieve rapid user onboarding (minutes instead of days) and zero-touch team scaling using Infrastream Agent and Infrastream's group-based access model. By the end of this guide, you'll be able to:

✅ Onboard new team members in minutes using Infrastream Agent to create access requests
✅ Manage entire teams via groups for instant onboarding and offboarding
✅ Maintain complete audit trails for SOC2, ISO 27001, and HIPAA compliance
✅ Enforce Zero Trust principles with precisely scoped project permissions

This implements business use cases:

How It Works: The Infrastream Agent Workflow​

Access management follows a simple, governed workflow:

  1. Manager initiates request → Uses Infrastream Agent in the portal: "Add jane-smith to the payments-contributors group"
  2. Infrastream Agent creates PR → Automatically generates a Pull Request modifying the group manifest
  3. Approval workflow → PR routes to organization administrators for review
  4. Instant provisioning → Once merged, user gets access within 2-5 minutes
  5. Permanent audit trail → Git commit records who requested, who approved, when granted

Why Infrastream Agent? By using Infrastream Agent instead of manual file editing, you get:

  • Simplified workflow for non-technical managers
  • Consistent manifest formatting
  • Built-in validation before submission
  • Integration with approval workflows

Understanding Project Permissions​

Infrastream projects support three permission levels, each with specific capabilities:

Permission Levels​

RoleCapabilities
AdministratorsFull control: manage resources, modify permissions, delete project
ContributorsCreate and modify resources, deploy applications, cannot change permissions
ViewersRead-only access to view resources and configurations

You grant access via Infrastream Name Abstractions. These reference the metadata.name of the corresponding identity manifests:

  • Users: Referenced by their OrganizationUser name (e.g., jane-smith).
  • Groups: Referenced by their OrganizationUserGroup name (e.g., payments-contributors).

[!IMPORTANT] Production Security Rule: Individual members (members:) are strictly disallowed for production and financial projects. All access must be granted via groups (groups:) to ensure compliance (SOC2/PCI) and scalable governance.

Use Case 1: Managing Team Membership via Groups​

Business Goal: Enable rapid onboarding with full accountability, eliminating IT ticket delays.

Scenario​

A new developer, Jane Smith (jane-smith), joins your team and needs contributor access to the astrapay-prod project. Instead of adding her directly to the project (which is restricted in production), you'll add her name abstraction to the payments-contributors group.

The Infrastream Agent Approach​

Step 1: Initiate request via Infrastream Agent

In the Infrastream portal, use Infrastream Agent:

Infrastream Agent: How can I help you today?
You: Add jane-smith to the payments-contributors group

Infrastream Agent:I have successfully created a Pull Request to add `jane-smith` to the `payments-contributors` group.

Since the the user `jane-smith` did not exist, I created manifests for both:
1.  **User**: `jane-smith` (Jane Smith)
2.  **Group**: `payments-contributors` (with `jane-smith` as a member)

You can review the changes here: [PR #10](https://github.com/astrapay/astrapay-infrastream-organization-manifests/pull/10)

Step 2: Approval and merge

Once an admin approves and merges, Jane gets access within 2-5 minutes.

Alternative: Manual Manifest Editing​

If you prefer to edit manifests directly (for advanced users):

Step 1: Locate the Project Manifest​

Navigate to your project manifest file:

organizational-unit/payments/
└── environment/production/
    └── project/astrapay-prod/
        └── astrapay-prod.yaml

Step 2: Edit the Project Manifest​

Open the project manifest and locate the permissions section. Add Jane's email to the contributors.members list:

apiVersion: lowops.manifests.v1
kind: Project
metadata:
  name: astrapay-prod
  environment: production
  organizational-unit: payments
  organization: acme-corp
spec:
  description: AstraPay Payment Processing Platform
  permissions:
    administrators:
      groups:
        - platform-team  # Name abstraction
      members: []      # Production Policy: Keep empty
    contributors:
      groups:
        - payments-contributors
      members: []
    viewers:
      groups:
        - qa-team
      members: []

Step 3: Submit and Merge​

  1. Create a Pull Request with your changes
  2. Request approval from a project administrator
  3. Merge the PR once approved

Result: Within minutes of merging, Jane will have contributor access to the astrapay-prod project. She can deploy applications, create databases, and manage secrets—but cannot modify project permissions.

Audit Trail​

The Git history provides a complete audit trail:

  • Who requested the access (PR author)
  • When it was requested (PR timestamp)
  • Who approved it (PR reviewer)
  • When it was granted (merge timestamp)

Use Case 2: Adding a Group to a Project​

Scenario​

Your organization has a GitHub team called backend-developers with 25 members. You want to grant this entire team contributor access to the api-gateway project rather than adding 25 individual users.

Step 1: Verify the Group Manifest Exists​

Ensure your team has an OrganizationUserGroup manifest defined at the organizational level. The project manifest relies entirely on this abstraction so that underlying identity providers remain decoupled.

For this example, we'll assume an OrganizationUserGroup manifest named backend-developers exists.

Step 2: Update the Project Manifest​

apiVersion: lowops.manifests.v1
kind: Project
metadata:
  name: api-gateway
  environment: production
  organizational-unit: platform
  organization: company
spec:
  description: Central API gateway service
  permissions:
    administrators:
      groups:
        - platform-leads
      members: []
    contributors:
      groups:
        - backend-developers  # ← References the OrganizationUserGroup manifest name
      members: []
    viewers:
      groups:
        - frontend-developers
        - mobile-developers
      members: []

Step 3: Submit and Merge​

Follow the same PR process as individual user access.

Benefits of Group-Based Access​

BenefitImpact
Zero-Touch OnboardingWhen HR adds someone to backend-developers, they automatically get project access
Instant OffboardingRemove from group = instant access revocation across all projects
ConsistencyEvery team member has identical permissions
ScalabilityManage 1 group instead of 25 individual entries

Use Case 3: Granting Temporary Access​

Scenario​

An external consultant needs viewer access to the customer-portal project for 2 weeks to perform a security audit.

Approach​

Add the consultant as an individual member with a comment indicating the temporary nature:

spec:
  permissions:
    viewers:
      groups:
        - security-auditors-2025-q1  # Use a time-boxed group abstraction
      members: []                  # Avoid direct assignment

Best Practice for Temporary Access​

  1. Add a comment with the expiration date directly in the manifest
  2. Create a calendar reminder to remove the access
  3. Consider creating a dedicated group (security-auditors-2025-q1) if multiple consultants need similar access

Use Case 4: Multi-Environment Access Strategy​

Scenario​

You want to implement a progressive access model where:

  • All developers can access development
  • Only senior developers can access staging
  • Only leads can access production

Implementation​

Create three different permission configurations across environments:

Development Environment (environment/development/project/customer-portal/customer-portal.yaml):

spec:
  permissions:
    contributors:
      groups:
        - all-developers  # Everyone can contribute in dev
      members: []

Staging Environment (environment/staging/project/customer-portal/customer-portal.yaml):

spec:
  permissions:
    contributors:
      groups:
        - senior-developers  # Restricted group for staging
      members: []
    viewers:
      groups:
        - all-developers  # Others can view staging

Production Environment (environment/production/project/customer-portal/customer-portal.yaml):

spec:
  permissions:
    administrators:
      groups:
        - tech-leads
    contributors:
      groups: []  # No one except admins can modify production
    viewers:
      groups:
        - senior-developers  # Restricted view access

Common Access Patterns​

Pattern 1: Platform Team Oversight​

Grant the platform team administrator access to all projects for governance:

spec:
  permissions:
    administrators:
      groups:
        - platform-team  # Consistent across all projects
        - project-owners  # Project-specific owners

Pattern 2: Read-Only Stakeholder Access​

Grant business stakeholders and product owners viewer access:

spec:
  permissions:
    viewers:
      groups:
        - product-managers
        - business-analysts
        - customer-success

Pattern 3: Contractor Isolation​

Create dedicated groups for contractors to easily manage access across multiple projects:

spec:
  permissions:
    contributors:
      groups:
        - contractors-2025-q1  # Time-boxed contractor group

Removing Access​

Removing a User from a Group​

The primary way to revoke access is removing the user abstraction from the group manifest:

File: organization/acme-corp/organization-user-group/payments-contributors.yaml

spec:
  members:
    users:
      - tech-lead
      # - jane-smith  # Removed - access revoked

Removing a Group​

Delete the group from the groups list:

spec:
  permissions:
    contributors:
      groups:
        # - external-contractors  # Removed - contract ended
        - backend-developers

Important: Removing access happens instantly upon merge. The user/group will immediately lose access to all project resources.

Environment-Level Permissions​

While this guide focuses on project-level access, you can also manage permissions at the environment level for broader control.

Environment Manifest (environment/production/environment.yaml):

apiVersion: lowops.manifests.v1
kind: Environment
metadata:
  name: production
  organizational-unit: platform
  organization: company
spec:
  description: Production environment
  permissions:
    administrators:
      groups:
        - platform-leads
    contributors:
      groups:
        - senior-engineers
    viewers:
      groups:
        - all-engineers

Environment permissions provide a baseline that can be further restricted at the project level.

Verification​

After merging your access changes, verify the changes took effect:

1. Check IAM Bindings (Cloud Console)​

Navigate to the GCP project and verify IAM bindings reflect your changes.

2. Test Access​

Ask the new user to:

  1. Attempt to view project resources
  2. Try deploying an application (if contributor)
  3. Attempt administrative actions (should fail if not admin)

3. Review Audit Logs​

Check Cloud Audit Logs for the permission grant event.

Security Best Practices​

1. Principle of Least Privilege​

Grant the minimum permission level needed:

  • Use viewer for stakeholders who only need visibility
  • Use contributor for developers who build and deploy
  • Use administrator only for project leads and platform teams

2. Prefer Groups Over Individuals​

Groups provide better:

  • Scalability: Manage permissions once, apply to many
  • Auditability: Clear team membership in one place
  • Maintainability: Less manifest clutter

3. Regular Access Reviews​

Periodically review project permissions:

# Search for all user grants across projects
grep -r "members:" organizational-unit/*/environment/*/project/

4. Document Temporary Access​

Always add comments for temporary access grants with expiration dates.

Troubleshooting​

Problem: User Added But Cannot Access​

Possible Causes:

  1. PR not yet merged
  2. User not authenticated with correct identity
  3. Typo in email address

Solution: Verify the manifest was merged and the email exactly matches the user's identity.

Problem: Group Access Not Working​

Possible Causes:

  1. Group doesn't exist in your identity provider
  2. Group name misspelled
  3. User not actually a member of the group

Solution: Verify group membership in GitHub/Google Admin and confirm exact group name.

Next Steps​

Now that you understand access management, explore: