Self-Service Access Guide

How Access Works

Keycloak is the source of truth for all identity and access. When you're added to a Keycloak group, access to corresponding systems is granted automatically within minutes.

For New Employees

Day 1: Automatic Provisioning

When HR adds you to the system, you automatically get:

1. Keycloak Account

   • Email sent with setup instructions
   • Set up MFA (required)
   • Username: firstname.lastname

2. Automatic Access (within 15 minutes):

   • Rocket.Chat → @firstname.lastname
   • Docusaurus → Read access to all internal docs
   • GitHub Organization → Read access to all repos
   • Netbird VPN → dev and staging networks
   • Email → firstname.lastname@company.com

First Week: Team Access

Your manager adds you to your team group in Keycloak:

Manager action in Keycloak:
Add user to group: "engineering-backend"

You automatically get (within 5-10 minutes):

• GitHub: Write access to @backend-team repositories
• Rocket.Chat: Added to #backend, #engineering channels
• Netbird: Access to backend-services network
• Staging: SSH access to backend staging servers

Requesting Additional Access

Option 1: Rocket.Chat Bot (Recommended)

Most access requests can be done via Rocket.Chat:

/access request github-team=frontend-team

What happens:

1. Bot verifies you're eligible (in engineering group)
2. Posts request in #access-requests channel
3. Your manager gets notification
4. Manager reacts with 👍 or 👎
5. If approved, Keycloak group updated automatically
6. You get GitHub access within 5 minutes

Common requests:

# GitHub team access
/access request github-team=frontend-team

# Production read access
/access request resource=production-read justification="On-call this week"

# VPN network access
/access request network=production-network justification="Debugging prod issue"

# Time-limited elevated access
/access request resource=prod-db-admin duration=4h incident=INC-123

Option 2: Direct Keycloak (For Managers)

If you're a manager, you can grant access directly:

1. Login to Keycloak admin: https://auth.company.com
2. Navigate to Users → Find user → Groups tab
3. Add user to appropriate group
4. Access syncs automatically

Option 3: Ansible PR (For SSH/Server Access)

For SSH access to specific servers:

1. Fork infrastructure repo
2. Edit inventory/group_vars/all/users.yml:

   team_members:
     - username: john.doe
       ssh_key: "ssh-ed25519 AAAAC3Nza..."
       groups:
         - backend-team
         - sudo  # Only if admin access needed

3. Create PR → CI validates → Merge
4. Ansible runs automatically, provisions access within 30 min

Access Levels by System

GitHub

Group	Access
engineering	Read all repos
engineering-frontend	Write to frontend repos
engineering-backend	Write to backend repos
engineering-devops	Write to infrastructure repos
github-admins	Org admin (CTO, VP Eng only)

Self-service: Request team group via bot Approval: Manager emoji in < 5 min

Netbird VPN

Network	Purpose	Auto-granted to
dev	Development servers	All engineering
staging	Staging environment	All engineering
production-read	Prod access (read-only)	On request (manager approval)
production-admin	Prod admin access	On request (security + manager)

Self-service: Production read access Manual approval: Production admin (requires justification)

DigitalOcean

Role	Access	Who
Viewer	Read-only, see all resources	All engineering
Developer	Manage dev/staging resources	Engineering (auto)
Admin	Full access	DevOps team only

Managed via: Keycloak SSO + DigitalOcean teams Self-service: Developer access Manual: Admin access (DevOps lead approval)

SSH/Server Access

Group	Access
dev-access	SSH to dev servers
staging-access	SSH to staging
prod-readonly	SSH to prod (no sudo)
prod-admin	SSH to prod (sudo)

Managed via: Ansible playbook syncs SSH keys Self-service: Dev/staging Approval needed: Production access

Production Access

Production access is time-limited and logged.

Production Read Access

Who can request: Any engineer Approval: Manager (via emoji) Duration: 7 days, auto-expires Includes:

• Netbird VPN access to prod network
• SSH read-only (no sudo)
• Application logs (read-only)
• Monitoring dashboards

How to request:

/access request resource=production-read duration=7d justification="On-call rotation"

Production Write Access

Who can request: Senior engineers, on-call engineers Approval: Manager + security notification Duration: Default 4 hours, max 24 hours Includes:

• Sudo access on application servers
• Database admin access
• Deployment permissions
• Service restart capabilities

How to request:

/access request resource=production-write duration=4h incident=INC-2025-001

Automatically revoked when:

• Time expires
• Incident is closed
• User explicitly releases access

Break-Glass Emergency Access

When to use: Critical production incident, on-call engineer needs immediate full access

How to request:

# In #incidents channel
/access emergency resource=root-access incident=INC-2025-001

What happens:

1. Immediate grant (< 1 minute)
2. Security team notified
3. Full audit trail
4. Auto-revoked after 4 hours
5. Requires post-incident explanation

Use sparingly: Triggers security review

Access Removal

Automatic Removal

Access is automatically removed when:

• Employee leaves (HR triggers Keycloak disable)
• Time-limited access expires
• Inactive for 30 days (account suspended, must re-activate)
• Failed to complete quarterly access review

Manual Removal

If you no longer need access:

/access revoke resource=production-read

If you're a manager removing access:

1. Go to Keycloak
2. Remove user from group
3. Access removed from all systems within 10 minutes

Troubleshooting

"I requested access but don't have it yet"

• Check #access-requests channel - was it approved?
• Wait 5-10 minutes for sync
• GitHub: Check your email for GitHub invitation
• SSH: Wait for Ansible to run (every 30 min)

"I can't login to X system"

• Verify your Keycloak account is active
• Check MFA is set up
• Try logging out and back in
• Check Keycloak group membership

"My access expired"

• Time-limited access expires automatically
• Re-request if still needed
• Check Rocket.Chat for expiration notifications

"Access request denied"

• Check with your manager for reason
• May need more specific justification
• Some access requires security approval

Still stuck?

• Post in #it-support channel
• Tag @devops team
• Include: what you're trying to access, error message, your username

Access Review Process

Quarterly Reviews

Every quarter, managers review their team's access:

1. GitHub Action generates report (first Monday of quarter)
2. Posted to Rocket.Chat #access-review-Q1-2025 channel
3. Managers review their team members' access
4. Certify with emoji:
   • ✅ = Access appropriate, keep
   • 👤 = Should be changed (add comment)
   • ❌ = Remove access
5. Automated enforcement within 24 hours

Example report:

@manager-john Q1 2025 Access Review for Backend Team:

jane.doe:
  - github: @backend-team, @devops (write)
  - prod-access: read (expires 2025-01-15)
  - ssh: dev, staging, prod-readonly
  React: ✅ to certify, ❌ to revoke, 👤 to modify

tom.smith:
  - github: @backend-team (write)
  - ssh: dev, staging
  React: ✅ to certify, ❌ to revoke, 👤 to modify

Deadline: 2 weeks to complete Non-completion: Escalated to VP Engineering

Best Practices

✅ Do:

• Request minimum necessary access
• Set time limits on elevated access
• Remove access you no longer need
• Keep SSH keys rotated (annually)
• Use MFA everywhere it's available

❌ Don't:

• Share credentials with teammates
• Use personal accounts for company resources
• Keep elevated access longer than needed
• Work around access controls
• Grant access without understanding why it's needed

Emergency Contacts

• Access issues: #it-support or @devops
• Security concerns: #security or @security-team
• Manager not responding: Escalate to their manager
• Keycloak down: Contact @devops immediately