Skip to main content

Onboard a new staff member into Entra

Procedure for adding a new AlphaSwarm employee to the company's Entra directory and granting them the right level of access to the managed AlphaSwarm platform.

This is a HR + Security workflow that does NOT touch Terraform. Group membership is intentionally outside Terraform's purview (rollout plan §1.2); Terraform owns which groups exist + what roles they confer, not who is in them.

Inputs​

  • The new hire's full name + corporate email address.
  • Their HR-side role (engineer, ops, compliance, finance, …).
  • The hiring manager's approval (capture the ticket id for the audit).

Steps​

1. Create the Entra user​

If the new hire doesn't already have an Entra account from corporate onboarding, create one:

az ad user create \
    --display-name "First Last" \
    --user-principal-name first.last@wiley-tech.onmicrosoft.com \
    --password "$(uuidgen | tr -d '-' | head -c 24)Aa!1" \
    --force-change-password-next-sign-in true

The auto-generated password is changed on first login; the operator NEVER stores or shares it.

2. Add to the appropriate AlphaSwarm group​

Map the HR-side role to the canonical group. Default mappings:

HR roleEntra group(s)
Software Engineer / SREAlphaSwarm-Engineering
Senior SRE / on-call rotationAlphaSwarm-Engineering + AlphaSwarm-Operations
Compliance OfficerAlphaSwarm-Compliance
Internal AuditorAlphaSwarm-Auditors
Finance / FinOpsAlphaSwarm-Finance
Security EngineerAlphaSwarm-SOC
CTO / VP EngineeringAlphaSwarm-Admins (requires CTO sign-off and CA-policy MFA)

Add via the Azure Portal OR via CLI:

# Look up the group id (cached locally for repeat use).
GROUP_ID="$(az ad group show --group AlphaSwarm-Engineering --query id -o tsv)"
USER_ID="$(az ad user show --id first.last@wiley-tech.onmicrosoft.com --query id -o tsv)"
az ad group member add --group "${GROUP_ID}" --member-id "${USER_ID}"

3. Verify the role propagation​

Wait 5 minutes for Entra to propagate, then have the new hire sign in once at manage.alpha-swarm.ai. The application token they receive should include the roles claim mapped to the group.

Confirm from the operator side:

python scripts/identity/list_entra_app_role_assignments.py \
    --format=json \
    | jq '.[] | select(.principal_display_name=="First Last")'

Should print one row per (role) for each group the user is in.

4. Capture the audit trail​

The Entra audit log records group-membership changes automatically and forwards them to the corporate SIEM via the existing log stream. The manager's approval ticket gets attached as part of the standard employee onboarding packet.

Promoting an existing staff member​

# Add to a higher-privilege group (e.g. ops on-call).
az ad group member add --group AlphaSwarm-Operations --member-id "${USER_ID}"

For promotions to AlphaSwarm-Admins:

  1. The CTO must sign off in writing (ticket id captured).
  2. The user must have a registered FIDO2 hardware key (verified by the Security team).
  3. The user falls under the AlphaSwarm-Admins-MFA-Required Conditional Access policy automatically.

Off-boarding​

# Remove from every AlphaSwarm group; do NOT just disable the Entra account
# in case the user has cross-tenant memberships we don't manage.
for group in AlphaSwarm-Engineering AlphaSwarm-Operations AlphaSwarm-Auditors AlphaSwarm-Compliance \
             AlphaSwarm-Finance AlphaSwarm-SOC AlphaSwarm-Admins; do
  GROUP_ID="$(az ad group show --group ${group} --query id -o tsv)"
  az ad group member remove --group "${GROUP_ID}" --member-id "${USER_ID}" 2>/dev/null || true
done

After removal, capture an evidence snapshot:

python scripts/identity/list_entra_app_role_assignments.py \
    --format=csv > evidence/entra-after-offboarding-${USER_ID}-$(date +%F).csv

Common pitfalls​

PitfallMitigation
Adding a user to two conflicting groupsThe role union is granted; review with list_entra_app_role_assignments.py after every change
Group propagation lagAsk the user to wait 5 minutes between group add and login retry
User can't sign in despite group membershipCheck Conditional Access "What If" report for the user; CA may be blocking the sign-in
Stale group from a previous roleRemove the old group BEFORE adding the new one to keep the audit trail clean