Skip to content

User Lifecycle — Onboarding and Offboarding

User provisioning is automated via Semaphore templates that coordinate Google Workspace, Authentik, and AWS SES. The primary onboarding path is admin-driven via the "Onboard New Hire" Semaphore template.

Components

Component Role
Authentik (sso.shared.cwiq.io) Identity provider — SSO, group-based access control
Semaphore (semaphore.shared.cwiq.io) Automation UI — admins run templates to trigger lifecycle workflows
Google Workspace Email accounts (@cwiq.io), Google SSO identity source
GAM CLI tool for Google Workspace admin operations (runs in Docker on Semaphore server)
AWS SES Email delivery for welcome and notification emails

Teams

Team Authentik Group
DevOps devops-users
DataOps dataops-users
Software Engineering software-engineering-users
Research research-users
Service Desk service-desk-users

Team assignment determines which Authentik group a user belongs to. Application access is then controlled by group-based policies (see App Onboarding).

Onboarding a New Hire

This is the primary onboarding method. One Semaphore template creates everything.

Prerequisites

  • Admin access to Semaphore (https://semaphore.shared.cwiq.io)
  • New hire's personal email address (receives credentials here)
  • New hire's name, username, and team

Steps

  1. Open https://semaphore.shared.cwiq.io
  2. Navigate to the User Management view
  3. Run the Onboard New Hire template (ID 27)
  4. Fill in the survey:
Field Required Description Example
personal_email Yes New hire's personal email (receives credentials) john@gmail.com
user_first_name Yes First name John
user_last_name Yes Last name Doe
user_team Yes Team dropdown DevOps
user_username Yes CWIQ username — email will be username@cwiq.io john.doe
grant_admin No yes = team-scoped admin access no
grant_m365 No yes = M365 Business Premium license no
  1. Click Run. The template executes the authentik/onboard-new-hire.yml playbook.

What Gets Created

  1. Google Workspace account (username@cwiq.io) with temporary password
  2. User added to cwiq-io-pilot GWS group
  3. Authentik user created with team attribute
  4. Team group assigned (e.g., devops-users)
  5. Default groups assigned: semaphore-users, aws-users
  6. Role-based application groups assigned by team (see table below)
  7. If grant_admin=yes: team-scoped admin groups added
  8. If grant_m365=yes: user added to cwiq-io-m365 GWS group → Azure Entra SCIM sync → M365 license assigned
  9. Nexus user created with nx-developer role (skipped for Service Desk)
  10. Welcome email sent to personal address with cwiq.io credentials

Application Access by Team (Default After Onboarding)

App DevOps DataOps / SE / Research Service Desk
Shared GitLab User User —
Dev GitLab User User —
Vault User User —
Taiga Admin User User
Icinga Admin User User
Grafana Admin User User
SonarQube Admin User —
DefectDojo Admin User —
AWS Console Developer ReadOnly —
Semaphore User User User

New Hire Getting Started

  1. Sign in to Google Workspace (https://workspace.google.com) with temporary password, change when prompted
  2. Visit https://sso.shared.cwiq.io, click "Sign in with Google"
  3. All assigned applications appear in the portal

Troubleshooting Onboarding

Symptom Cause Fix
GWS account already exists Prior account present Playbook warns admin, skips creation. No credentials email sent. Manually verify group membership.
Authentik user already exists User logged in via Google OAuth first Playbook skips creation, continues with group assignment.
Email not received SES credentials expired or spam filter Check Semaphore environment vars for SES. Check SES delivery logs.
Team group not found Groups not created Run policies/configure-team-groups.yml

Existing User — First SSO Login

For users who already have a @cwiq.io Google account but have never used Authentik. No admin action required.

  1. User visits https://sso.shared.cwiq.io
  2. Clicks "Sign in with Google", authenticates with cwiq.io account
  3. Authentik auto-creates the Authentik user account via Google OAuth source
  4. First login: team selection prompt appears
  5. User picks their team from the dropdown
  6. Authentik assigns the matching {team-slug}-users group via expression policy
  7. User can access applications assigned to their team

If the prompt does not appear, run policies/configure-team-selection.yml from the ansible server.

Offboarding a User

Steps

  1. Open https://semaphore.shared.cwiq.io
  2. Run the Offboard User template (ID 15)
  3. Enter the user's @cwiq.io email and confirm with CONFIRM

What Happens

  1. Authentik user deactivated (account preserved for audit trail)
  2. User removed from all Authentik groups
  3. Google Workspace account suspended
  4. Admin notification email sent to admin@cwiq.io
  5. AWS Identity Center: AWS SCIM sync runs automatically, removing AWS access

Post-Offboarding Checklist

After the Semaphore template completes, verify manually:

  • [ ] User cannot log in to sso.shared.cwiq.io
  • [ ] User's cwiq.io email is suspended in Google Workspace Admin Console
  • [ ] AWS Access Keys (if any) revoked via IAM Console
  • [ ] User removed from any shared service accounts or tokens

Semaphore Templates Reference

All templates are in the User Management view at https://semaphore.shared.cwiq.io.

ID Template Playbook Key Variables
27 Onboard New Hire authentik/onboard-new-hire.yml personal_email, user_first_name, user_last_name, user_team, user_username, grant_admin, grant_m365
14 Onboard User authentik/onboard-user.yml user_email, user_first_name, user_last_name, user_team, grant_m365
15 Offboard User authentik/offboard-user.yml user_email, confirm_offboard
16 Create User authentik/users/create-user.yml user_email, user_name, user_username
17 Deactivate User authentik/users/deactivate-user.yml user_email
18 Delete User authentik/users/delete-user.yml user_email
20 Add User to Group authentik/groups/add-user-to-group.yml user_email, group_name
21 Remove User from Group authentik/groups/remove-user-from-group.yml user_email, group_name
23 Promote User to Admin authentik/promote-to-admin.yml admin_username, admin_team
24 Create Admin User authentik/users/create-admin-user.yml user_email, user_name, user_username
25 Create Enrollment Invitation authentik/create-invitation.yml invite_label, invite_expires_hours, invite_single_use

All templates share: environment_id: 3 (Authentik Shared), repository_id: 1, inventory_id: 1.

CLI Operations (Ansible Playbooks)

Run directly from the ansible server when Semaphore is unavailable or for batch operations:

ssh ansible@ansible-shared-cwiq-io
ansible-helper
cd authentik

# List users
ansible-playbook -i inventory.ini users/list-users.yml

# Create a user
ansible-playbook -i inventory.ini users/create-user.yml \
  -e "user_email=jane.smith@cwiq.io"

# Add user to group
ansible-playbook -i inventory.ini groups/add-user-to-group.yml \
  -e "user_email=jane.smith@cwiq.io" \
  -e "group_name=vault-users"

# Deactivate user (offboarding)
ansible-playbook -i inventory.ini users/deactivate-user.yml \
  -e "user_email=jane.smith@cwiq.io"

# Full offboarding (deactivate + remove groups + suspend GWS)
ansible-playbook -i inventory.ini offboard-user.yml \
  -e "user_email=jane.smith@cwiq.io" \
  -e "confirm_offboard=CONFIRM"