Project Onboarding - Automate 1Password Vault Access Management

[wesley115]

Overview

Automate 1Password vault access management for HACK for LA member project onboarding/offboarding. When members join or leave a project, their vault access should be automatically granted or revoked via integration with the existing Google Apps Script onboarding system.

Details

Currently, vault access management is manual and inconsistent. When members offboard, their 1Password vault access is often not revoked—creating a security risk. Manual management doesn't scale with 500+ vaults and frequent volunteer turnover.

Action Items

• Create a new branch (e.g., feature/implement-1password).
• Working API deployed on personal AWS EC2 (temporary)
• Migrate API to HFLA Incubator (Terraform/ECS)
• Add HTTPS via ALB
• Organize project vaults and define role permissions (Vault Spreadsheet)
• Integrate with production onboarding spreadsheet
• Submit a PR for code review.
• Create documentation for maintenance

Resources/Instructions

• https://github.com/1Password/connect
• https://developer.1password.com/docs/cli/reference/
• https://developer.1password.com/docs/connect/
• https://developer.1password.com/docs/connect/api-reference/

[wesley115]

Key Findings

1. 1Password Connect Server - Limited API

Successfully set up Connect Server on AWS, but the API only manages vault items (secrets), not vault user access. Cannot grant/revoke user permissions via Connect API.

[Connect API Reference](https://developer.1password.com/docs/connect/api-reference/)

2. Service Accounts Cannot Manage Vault Users

Attempted to use Service Accounts for automation. Critical limitation discovered: Service Accounts can only read/write vault items—they cannot manage user permissions.

Error received:

"the vault permission manage_vault is not valid for service accounts"

This is a fundamental architectural limitation of 1Password, not clearly documented.

3. SCIM Bridge Not Viable for HFLA

Investigated 1Password SCIM (System for Cross-domain Identity Management) for automatic user provisioning. Not suitable because:

• Requires Google Workspace integration (additional cost)
• Only works for @hackforla.org email addresses
• HFLA volunteers use mixed domains (Gmail, personal, work emails)

4. Working Solution: CLI-Based Vault Access API

Use 1paaword CLI with Human Bot Account

Google Apps Script (onboarding spreadsheet)
       ↓ HTTP POST
Node.js API (port 3000)
       ↓ Authenticates via CLI
1Password CLI (as bot user: tables@hackforla.org)
       ↓ Executes vault user grant/revoke
1Password Cloud (hackforla-team.1password.com)

Why this works:

• Human user accounts (not service accounts) CAN manage vault permissions
• 1Password CLI authenticated as a human user has full permission management capabilities
• Node.js API wraps CLI commands and exposes them as REST endpoints

Created sub-issue for solution implementation and migration to Incubator: #[ISSUE_NUMBER]

[wesley115]

As we now have a working 1Password vault access management API currently hosted on my personal AWS EC2 instance (before migrating to the incubator), we can move forward with implementing the feature for project onboarding automation.
To do this, we need to perform some cleaning and organization of the vaults for each project, including defining role permissions.

Here's the link to the spreadsheet for reference: https://docs.google.com/spreadsheets/d/1DCWo6ZLBGqIBK07k-uckVH-STcBAChzFGaBdVp8c-Kw/edit?gid=1285713776#gid=1285713776

[wesley115]

onboard
onboard member according to role permission

offboard

1. Check if their emails are in the "people" database on 1pwd:
   if so, offboard them from every vault in the project and only report number of vault they got remove
   if not, report error
2. After offboarding, check if they belong to any other project:
   if so do nothing
   if not, remove them from zoom vault

[wesley115]

Key Findings

• The 1Password web-based UI is the only way to directly send an invitation to a user when sharing a vault.

• There isn't a direct way to use the 1Password CLI to share a vault with an uninvited user. The op vault user grant command requires the user to already exist in your 1Password account, meaning they must be invited (via op user provision) and confirmed first before you can grant them vault permissions. Attempting to use an email of an uninvited person with --user won't work, as they aren't recognized in the system yet.

• When inviting a user to 1Password, the user has 5 days to accept the invitation, as shown in the picture below:

• (UPDATE) The 1Password CLI op user provision command requires a Business plan (see documentation).

  With the current Team plan, available commands include
  op user suspend,
  op user reactivate,
  op user delete,
  and op user get to check user states (e.g., ACTIVE, PENDING—user has accepted the invitation and is waiting for admin confirmation, SUSPENDED, or not a user in the account, such as when an invite has been sent but not yet accepted).

However, op user provision cannot be used to invite users, and op user confirm (individual or --all) is not available.

Besides upgrading to a Business plan, to automate this process, I added these four additional API endpoints:

Route	Purpose	Key behavior
POST /check-user	Gate for every pipeline step	Returns { exists, state, userId } — the state field drives GAS logic
POST /invite	Send invitation email	Guards against re-inviting: returns 409 if user already exists in any state
POST /user/confirm	Confirm a specific PENDING user	Returns 404 (not found), 409 with reason if state isn't PENDING (e.g. INVITED = hasn't clicked link yet), or alreadyActive: true if already done
POST /user/confirm-all	Confirm all PENDING users	Always returns 200; confirmedCount: 0 if nobody was pending

Workaround Options (UPDATE both not viable with current 1pwd team plan)

1. Onboard every new member to 1Password during the general onboarding process. Set up a confirmation trigger five days later to ensure every new member is in 1Password. When onboarding someone to a project who is not in the 1Password database, flag them and ask the PM to invite them to 1Password or to directly share the vault with them.

2. When onboarding a member who isn't in the 1Password "people" database:

   • Invite them to the HFLA 1Password account via the API (the member would have 5 days to confirm the pending invitation).
   • Figure out a mechanism to automate the confirmation (we can currently do "confirm all" or "confirm individual").
   • Using "confirm individual": This is better since we could minimize the pending domain and only confirm the user that is related to the specific onboarding task.
   • Using "confirm all": We still need to separate the task of which user to onboard to which project, thus a state record is still required.
   • We need a way to check for pending individuals, confirm them, then continue the onboarding and add them to the vault. As a result, "confirm individual" should be bundled with adding them to the vault.
   • Limitation: If setting up a time-based trigger, we need to figure out where to set it up. Google Apps Script has only a 20-trigger limit, and the AWS API server shouldn't handle such a job.

[wesley115]

1Password Vault Access — Full Pipeline

1Password vault access is managed is implemented to project on/offboarding. Since HFLA runs on the Teams plan, the CLI commands for automated user creation require Business tier and are unavailable ie. op user provision. User invitations must be done manually through the web UI. Everything else, including checking membership, looking up vaults, granting and revoking access are fully automated.

---

Onboarding — Two Stages

Onboarding is partially automated with human step required for members that has not been added to 1Password team.

Stage 1 — Runs automatically at project onboarding

The system calls POST /check-user against the HFLA 1Password team.

Volunteer already exists :
Vault IDs are retrieved from the all vaultsheet by project name with role flags, and access is granted immediately via POST /onboard. Pipeline complete in a single run.

Volunteer not yet in 1Password :
They are recorded in the 1Password Pending Invites sheet (status: 1. Needs to be invited) and the GitHub comment posts a warning with a direct link to that sheet. Vault grant is deferred to Stage 2.

Human step — PM action required (pending invite path)

1. Open the pending invites sheet from the GitHub comment link
2. Invite the volunteer at hackforla-team.1password.com/invitations
3. Change the status in the sheet to 2. Invited
4. Check invitees on hackforla-team.1password.com/invitations to see if they accepted.
5. Confirm accepted invites on hackforla-team.1password.com/invitations
6. Set their row status to **3. Confirmed**That cell change for column 1Password_status is the only trigger for Stage 2.

Stage 2 — Runs automatically on confirmation

The onChange trigger detects 3. Confirmed in the 1Password_status column and calls completePendingInviteOnboard(). It re-retrieves the project and role, looks up the correct vaults, and grants access through the same API path as Stage 1. On success, status updates to 4. Added to vaults and a confirmation comment is posted to Project Onboarding log issue.

Pending invite status progression

Status	Set by	Meaning
1. Needs to be invited	System	Volunteer not in 1Password — awaiting PM invitation
2. Invited	PM	Invitation sent, waiting for volunteer to accept
3. Confirmed	PM	Volunteer accepted — triggers Stage 2
4. Added to vaults	System	Vault access granted — pipeline complete
5. Failed to add to vaults	System	Grant failed — reset to 3. Confirmed to retry

---

Offboarding — Single Stage

Offboarding is fully automated with no human step required.

The system use member's github handle to retrieve the volunteer's email and calls POST /offboard for all vault IDs for the project from the all vault sheet (no role filter — full removal)

Zoom vault is handled separately: it is only revoked if the volunteer has no remaining projects after this offboarding. If they still belong to other projects, the Zoom vault is retained.

A pre-check via POST /check-user is not performed before offboarding — revocation is attempted directly. If the volunteer was never in 1Password, the API calls fail gracefully and are reported in the GitHub comment.

---

Vault Retrieval

Vault IDs are never hardcoded. They are retrieve at runtime from the all vault tab in the Roles spreadsheet, matched by:

• Project-specific vaults — row must match both the project name and the volunteer's active role flags
• Global vaults (e.g. Zoom) — matched by role map only, granted/revoked for any user regardless of project

For every vault operation, preferred_email is tried first with gmail as a fallback if the first attempt fails.

---

If something goes wrong

Scenario	What to check	How to recover
Stage 1 shows pending_invite	Volunteer not in 1Password	Invite via web UI, once accepted mark 3. Confirmed
Stage 2 shows 5. Failed	Volunteer may not have accepted yet, or API credentials issue	Verify acceptance, then reset to 3. Confirmed
Offboard vaults not fully removed	Check GitHub comment for per-vault failure details	Re-run offboarding or revoke manually in 1Password web UI
Zoom vault unexpectedly removed	Volunteer still had remaining projects at offboard time	Check project_name field in Volunteers sheet

All runs — success, partial failure, or total failure — post a GitHub comment to this issue with per-vault results. Full step-by-step execution logs are in Apps Script → Executions (only record for 7 days) or HFLA project automation log (store permanently).