Access Reviews and Internal Role Changes
If you are preparing for SOC 2, ISO 27001, or any audit that examines logical access controls, the most common finding around DeployHQ access is not orphaned accounts from people who have left the company. Those tend to get cleaned up by your offboarding workflow. The harder gap is stale permissions from internal role changes: an engineer becomes a product manager, an IC becomes a manager, someone moves teams. Their account is still active, they still need DeployHQ access, but they should no longer have access to the projects and servers from their previous role.
Access reviews that only ask "does this person still work here" and "do they still need their current access" miss this. The question that catches it is "should this person still have access from their previous role" — and you only get a clean answer by comparing what is actually provisioned in DeployHQ against the access your HR or identity system says each role should have.
This article describes the recommended pattern for building that review on DeployHQ. It is a defense-in-depth approach: SSO, API-based reconciliation, and a lightweight process control. None of the three is sufficient on its own; together they close the gap.
What SAML SSO covers, and what it does not
SAML SSO on the Enterprise plan gives you centralised authentication and, with enforcement enabled, reliable offboarding. With Enforce SSO (disable password login) turned on, password authentication is disabled and disabling a user in your identity provider immediately blocks their ability to log in to DeployHQ. Without enforcement, SSO sits alongside password login rather than replacing it — a user disabled in the IdP can still sign in with their DeployHQ password, so the IdP disable does not by itself revoke access. For audit-grade offboarding, enable enforcement in your SAML SSO configuration. This is the primary control for the "person leaves the company" case, and it should be your first layer.
What SSO does not currently cover:
- Group or role mapping. DeployHQ's SAML integration maps the user's email, first name, and last name. It does not map your IdP groups or roles to DeployHQ project, server, or account-administrator permissions. Moving a user from one group to another in your IdP does not change what they can see or do inside DeployHQ.
- Automated provisioning of fine-grained access. A user authenticated via SSO still has whatever permissions were granted to their DeployHQ account when it was created or last edited. Those permissions live inside DeployHQ and are not synchronised from the IdP on each login.
This means SSO catches the "should this person be able to log in at all" question, but not the "what should this person have access to once they are in" question. Internal role changes fall squarely in the second category.
Layer 2: Periodic reconciliation via the Users API
The control that actually catches stale permissions from internal transfers is a periodic reconciliation between your source of truth for role membership (an HR system, an IdP group, a team directory) and the user list in DeployHQ.
The shape of the job is straightforward:
- Pull the expected list of DeployHQ users for each role from your source of truth. For each user, derive the set of projects, servers, and account-level privileges they should have, based on their current role.
- Pull the actual list of DeployHQ users and their permissions using the Users API.
- Diff the two. Surface any user whose actual permissions differ from what their current role would justify, in either direction (over-provisioned or under-provisioned).
- Treat each diff as a review item. Either correct the permissions in DeployHQ to match the role, or document why the difference is intentional.
The endpoints you will most commonly use:
- List Users returns every user in your account, with their account-level role.
- View User returns a single user's full configuration, including project access.
- Update User lets you change a user's role or remove them from projects they should no longer have access to.
- Invite User and Remove User handle the create and destroy ends of the lifecycle.
The reconciliation job itself does not need to be sophisticated. A scheduled script that runs nightly or weekly, posts diffs to a Slack channel or a ticket queue, and waits for human review is enough to satisfy most auditors and to catch real drift before a quarterly review does. The artefact your auditor wants to see is the evidence that reviews are happening on a defined cadence, that diffs are being acknowledged, and that corrective action is logged.
If you prefer to build the review around manual sampling rather than automated reconciliation, the same Users API endpoints will give you the data you need to export a current snapshot for review.
Layer 3: Process control at the moment of change
Reconciliation is detection. The complementary control is prevention: catching the access change at the moment the role changes, rather than at the next quarterly review.
The pattern that works in practice is to add an access-revocation review step to your internal-transfer workflow, owned by HR or IT, that fires whenever an employee changes role or team. The trigger is the role change itself, not a calendar date. The review asks the new manager and the security or IT owner to confirm what access from the previous role should be removed before the transfer is finalised. For DeployHQ specifically, this is usually a five-minute task: open the user in DeployHQ, look at their project and server permissions, and remove anything that does not belong with the new role.
This control is what closes the window between role change and the next reconciliation cycle. Without it, a user who transferred two days ago will still show up clean on a monthly reconciliation report — they have the access their previous role required, the diff has not yet been generated. With it, the access is corrected at the source.
Putting the three layers together
| Layer | Catches | Cadence | Where it lives |
|---|---|---|---|
| SSO offboarding (with enforcement enabled) | Account disabled in IdP, user can no longer log in | Real-time, on next auth | Identity provider |
| API reconciliation | Permissions in DeployHQ that do not match what the user's current role should have | Scheduled (nightly or weekly) | Your reconciliation script |
| Role-change process | Stale access from internal transfers, before reconciliation runs | Triggered by role change in HR/IdP | HR or IT workflow |
For an auditor, the evidence package is: the SSO configuration in DeployHQ, the source code or job definition for the reconciliation script along with a sample of recent diff reports, and the documented role-change procedure with a sample of completed access-revocation reviews from the audit period.
Recovering from a finding
If your auditor has already flagged stale access from internal transfers and you need to remediate quickly, the fastest path is:
- Pull the current user list and per-user permissions from the Users API.
- Cross-reference against current role membership from your HR or IdP system.
- For each user whose DeployHQ permissions exceed what their current role should have, use Update User to remove the excess access, and document the change.
- Schedule the reconciliation job and the role-change review described above so the gap does not reopen.
If you would like help shaping any of this for your specific audit framework or identity provider, contact us at support@deployhq.com.