Brainforge Knowledge

add-user-azure-ai-resources-playbook

4 min read

Playbook: Add New User to Azure and AI Resources

Domain: Engineering / Operations
Artifact type: Playbook
Frequency: Per new team member
Status: Draft

Use When

A new team member joins Brainforge and needs:

  1. Access to Azure OpenAI resources (current workflow)
  2. Azure AD/Entra ID access (future workflow — for migration planning)
  3. Understanding of what AI resources they need based on their role

Current state: Brainforge uses Google Workspace for identity. Azure AD integration is documented for future migration.

Overview

This playbook covers:

  • Step 1: User role classification and required resources
  • Step 2: Azure OpenAI access provisioning (current)
  • Step 3: Azure AD/Entra ID user creation (future-ready)
  • Step 4: Role-based AI resource access matrix

Step 1: User Role Classification

Determine the user’s role and required access level:

RoleAzure OpenAIGitHubLinearNotion1PasswordOther
AI EngineerFull (East US 2)✓✓✓✓Cursor, Claude/ChatGPT
Platform EngineerFull (East US 2)✓✓✓✓Cursor, Vercel, Railway
Data EngineerRead (East US 2)✓✓✓✓Snowflake, BigQuery
Sales/MarketingLimited (API only)✓✓✓✓HubSpot, Figma
OperationsNone✓✓✓✓Linear, Clockify

Action: Record the role classification before proceeding.

Step 2: Azure OpenAI Access Provisioning (Current)

2.0 Service Principal (for automation)

For CI/CD pipelines and automated scripts, use the BrainForge Platform service principal.

Retrieve fresh credentials from 1Password:

# Get credentials from 1Password vault "Brainforge AI Team"
op item get "BrainForge Platform SP" --vault "Brainforge AI Team"
 
# If not found, create new:
# az ad sp create-for-rbac --name "BrainForge Platform"
# Then store the appId and password in 1Password

Role: Contributor (subscription level) Scope: Full subscription access

The service principal credentials should never be committed to the repository.

2.1 Retrieve Azure Credentials

# List available credentials in 1Password
op item list --vault "Brainforge AI Team"
 
# Get the Azure OpenAI API key
op item get "brainforge-openai-eastus2" --vault "Brainforge AI Team"

2.2 Azure OpenAI Resource Reference

ResourceEndpointModel DeploymentsUse Case
brainforge-openai-eastus2https://brainforge-openai-eastus2.openai.azure.comgpt-4o, gpt-4.1, gpt-5.4Primary — use for all new deployments
brainforge-openaihttps://brainforge-openai.openai.azure.comLegacyDeprecating — do not create new

2.3 Environment Variables to Share

For new users who need Azure OpenAI access, share these variables from 1Password:

AZURE_OPENAI_EASTUS2_API_KEY=<from 1Password>
AZURE_OPENAI_EASTUS2_BASE_URL=https://brainforge-openai-eastus2.openai.azure.com
AZURE_OPENAI_EASTUS2_API_VERSION=2024-05-01-preview
AZURE_OPENAI_EASTUS2_CHAT_MODEL=gpt-4o

2.4 Platform-Specific Setup

For platform engineers, also provide:

  • Copy apps/platform/.env.example to .env.local
  • Retrieve keys from 1Password: op item get "platform env" --vault "Brainforge AI Team"

Step 3: Azure AD / Entra ID User Creation (Future-Ready)

Note: Brainforge currently uses Google Workspace. This section is for future Azure AD migration planning.

3.1 Prerequisites

  • Azure subscription with Entra ID (formerly Azure AD)
  • Global Administrator or User Administrator role
  • Azure CLI authenticated: az login

3.2 Create New User

# Create new user in Entra ID
az ad user create \
  --display-name "FirstName LastName" \
  --user-principal-name "firstname.lastname@brainforge.onmicrosoft.com" \
  --mail-nickname "flastname" \
  --password "{temporary-password}" \
  --force-change-password-next-sign-in true
 
# Capture the userprincipalname (UPN) from output

3.3 Assign Role (if needed)

# Get role definition
az role definition list --output table | grep -i "user"
 
# Assign User Administrator (if delegating user management)
az role assignment create \
  --assignee "firstname.lastname@brainforge.onmicrosoft.com" \
  --role "User Administrator"

3.4 Add to Group (for resource access)

# Get group object ID
az ad group show --group "Brainforge-Engineers" --query objectId
 
# Add user to group
az ad group member add \
  --group "Brainforge-Engineers" \
  --member-id "<user-object-id>"

3.5 License Assignment

# Get available SKU
az account list-skus --output table
 
# Assign license (example: Microsoft 365)
az user update \
  --ids <user-object-id> \
  --usage-location US

Step 4: Role-Based AI Resource Access Matrix

4.1 OpenAI API Access

RoleAccess LevelDeploymentKey Source
AI EngineerFull read/writebrainforge-openai-eastus21Password “brainforge-openai-eastus2”
Platform EngineerFull read/writebrainforge-openai-eastus21Password “brainforge-openai-eastus2”
Data EngineerRead onlybrainforge-openai-eastus2Shared team key
Sales/MarketingAPI calls onlybrainforge-openai-eastus2Shared team key
OperationsNoneN/AN/A

4.2 Other AI Tools Access

ToolAll EngineersData TeamSales/MarketingOperations
OpenCode Desktop✓✓——
Claude/ChatGPT✓✓✓✓ (limited)
Cursor✓———
browser-use✓ (AI/Platform)———

4.3 Resource-Specific Setup

OpenCode Desktop + Azure OpenAI

Reference: knowledge/standards/03-knowledge/engineering/setup/opencode-desktop-azure-setup.md

// ~/.config/opencode/opencode.json
{
  "provider": "azure-eastus",
  "azure eastus": {
    "api_key": "${AZURE_OPENAI_EASTUS2_API_KEY}",
    "base_url": "https://brainforge-openai-eastus2.openai.azure.com",
    "model": "gpt-4o"
  }
}

browser-use + Azure OpenAI

Reference: knowledge/engineering/browser-use-azure-brainforge.md

# tools/browser-use-brainforge/brainforge_browser_use/llm.py
from langchain_openai import ChatAzureOpenAI
 
llm = ChatAzureOpenAI(
    azure_endpoint="https://brainforge-openai-eastus2.openai.azure.com",
    azure_deployment="gpt-4o",
    api_key=os.getenv("AZURE_OPENAI_EASTUS2_API_KEY"),
    api_version="2024-05-01-preview"
)

Step 5: Verification Checklist

After provisioning, verify access:

  • User can authenticate to Google Workspace (current)
  • User can access Azure OpenAI endpoint (ping test)
  • User can make API calls to East US 2 resource
  • User’s IDE/editor has correct environment variables (if applicable)
  • User can access required tools (Cursor, OpenCode, etc.)
  • 1Password access confirmed

Rollback (if needed)

Remove Azure AD User

# Get user object ID
az ad user show --id "firstname.lastname@brainforge.onmicrosoft.com" --query objectId
 
# Delete user
az ad user delete --id "<user-object-id>"

Revoke Azure OpenAI Key Access

Revoke by rotating the API key in 1Password and updating team members with new key.

  • knowledge/standards/01-onboarding/new-team-member-onboarding-sop.md — Full onboarding SOP
  • knowledge/standards/03-knowledge/engineering/setup/azure-openai-setup.md — Azure setup reference
  • knowledge/engineering/opencode-cli-brainforge.md — OpenCode CLI Azure config
  • apps/platform/.env.example — Platform Azure env vars
  • PLAYBOOK_INDEX.md — This playbook’s index entry

Changelog

DateChangeAuthor
2026-04-22Initial playbookBrainforge

Graph View