Approvals

Group join requests, vault check-out requests and the workflow Approval step used to have three approval mechanisms with three pages. They now share one decision model and one Approvals page in the portal. Each kind keeps its own request record, its own audit trail and its own action after the decision: the membership is written, the check-out can be made, or the run continues. What is shared is who may decide, how many decisions are needed, escalation and timeout, the rule that the requester and the subject never decide, operator override, withdrawal, notifications, and one list to work from. Approvals need the Enterprise tier.

This runbook covers the shared page and the shared rules. Each kind also has its own runbook: the step’s fields are in Workflow approvals, the group policies are in Join policies, and the vault policies are in Check-out approvals.

The Approvals page

Approvals in the sidebar, its own entry directly below Mesh Objects, at /identity/approvals. There is one sidebar entry for all three kinds. It is visible to anyone who holds any of workflows.approve, groups.own or vault.approve. The subtitle reads “Workflow steps, group joins and vault checkouts waiting on a decision”. On a tier below Enterprise the page says “Approvals require the Enterprise tier”.

The old pages redirect here with the kind filter preset, so old links in emails and inbox notices keep working:

You can preset the filter yourself with ?kind=Workflow, ?kind=GroupJoin or ?kind=VaultCheckout on the address.

Tabs

The kind filter offers All, Workflow, Group join and Vault checkout.

Columns

The title depends on the kind:

Deciding

Select Approve or Reject on the row. A dialog opens with a Reason (recorded in the audit trail) box. Confirm to record your decision.

On a vault row, the approve dialog also has Grant for (minutes). It is prefilled with the minutes the requester asked for. You can shorten it, from 1 up to the requested minutes, but you cannot lengthen it.

Your own request shows “Somebody else decides it (your request)” in place of the buttons.

A decision is refused when the request was already decided, when another decision landed first, or when the subject no longer exists. It is also refused when you are not permitted to decide it. Reload the page to see where the request stands.

Who can decide

The same rules apply to all three kinds.

• Approvers are mesh people. The portal links a signed-in person to their mesh object by matching the sign-in against the object’s userPrincipalName, mail or sAMAccountName.
• A group named as an approver is expanded. Its direct members are asked, up to 100. Above that, a warning is logged.
• The requester and the subject never decide. This holds for every kind, even for an operator.
• Each person decides once. One rejection settles the request as rejected. It is approved when the approvals reach the number needed: 1 for group joins and vault check-outs, and Approvals needed for a workflow step.
• Eligibility is checked when you decide. It is not only checked when the request opened. An owner removed from the group, or a person removed from the vault approver role, can no longer decide the requests that named them.
• Two stages are decided by different people. A two-stage request (dual control) shows its Stage on the page, and the person who decided stage 1 cannot decide stage 2. Only group joins use two stages today, for high-impact groups.

Each kind decides who is asked in the first place:

Escalation and timeout

When nobody has decided by the escalation time, the escalation set is told as well and can decide beside the first set. When nobody has decided by the timeout, the request times out.

Group and vault escalation and timeout are off until a policy sets them.

For group joins:

• escalation goes to the administrators, and only for groups that are not high impact. A high-impact group’s requests never escalate, because its second stage already belongs to the administrators,
• Join approval: escalate after must be shorter than Join approval: time out after. If it is not, the escalation is ignored,
• a group with no owner left escalates its open stage-1 requests to the administrators at once, when it is not high impact. A high-impact group keeps its requests open for the promoted owner, and administrators can reject them.

For vault check-outs, Escalation role names who an escalated request goes to. It is required when Escalate after is set.

Operator actions

Holders of a kind’s override permission can settle a request of that kind without being an approver: workflows.execute for workflow requests, groups.admin for group joins and vault.admin for vault check-outs.

Every operator action is recorded in the administrator audit trail as an operator decision, with who and the reason. An operator who is the requester or the subject of a request still cannot decide it.

Withdrawn requests

A request is withdrawn when:

• the requester withdraws their own group join or vault request. A vault request can also be withdrawn after approval, while it is unused,
• a holder of the kind’s override permission withdraws an open request,
• a workflow run is cancelled, fails or is deleted with its workflow. See Withdrawn requests,
• the subject is erased or deleted. The sweep notices this within about a minute,
• a group is deleted. Its open requests are withdrawn,
• a vault account is archived, including by the source-missing sweep. Its open requests are withdrawn.

The people asked are told when the request was still pending. Withdrawing an approved vault request nobody has used tells nobody, since nothing is asked of anyone.

Requesters withdraw from their own lists: Withdraw on /groups/requests (My Requests) for group joins, and Withdraw on the My requests tab of the Vault self-service page for vault requests.

After the decision

Each kind has its own follow-up action once a request is approved:

A vault approval is valid for the policy’s Approval valid for (minutes), 1440 (24 hours) by default. An approved request nobody checks out within that window becomes Expired, the requester is told, and they must request again.

A decided request whose follow-up action is still owed stays on All open. The approval sweep retries the action after a 30 second grace from the decision, up to five attempts. After that the request is marked failed and stays on Completion failed until someone selects Retry completion.

Notifications

Every person asked gets an inbox notice under the bell. When email is set up under Settings → Email and their person object has an email address, they get an email as well. Who hears the outcome depends on the kind: a workflow request tells its approvers, because the decision is theirs to know; a group join or a vault check-out tells the person it is about and, when someone else asked, the requester, because the decision is an answer to them.

The subject reads “prefix title (phase)”. The prefix is “Approval:” for a workflow request, “Group join:” for a group join and “Vault request:” for a vault check-out.

The body names the workflow for a workflow request, or reads “Request: group join” or “Request: vault checkout”. It continues with About: the subject and its type, Requested by: when the requester is not the subject, the justification, the approvals so far of the number needed, and, for a new request, when it escalates and times out in UTC.

The last line links to the page when the Portal URL is set under Settings → Email, Links:

Open: https://identitymesh.example.com/#/identity/approvals

Without a Portal URL, the email ends with:

Open the IdentityMesh portal and go to Approvals.

Enter the Portal URL as the plain address with no #. See Email.

Nothing is sent for a request that was approved automatically, such as a join to an open group or a check-out under a vault policy that does not require approval.

On a test install, every approval email can go to one mailbox instead of the real approvers and requesters. See Redirect for testing.

The approval sweep

A background pass in the Admin API runs every minute while the licence tier is Enterprise. It:

• escalates and times out group and vault requests at their deadlines,
• retries follow-up actions that did not complete, after a 30 second grace from the decision, up to five attempts,
• expires vault approvals nobody used within their window,
• re-checks open vault requests against current role membership: when the approver role has emptied since the request was filed, the request escalates at once if the escalation role had members when the request was filed and still reaches someone. Otherwise the vault administrators and the requester are told once, and the request does not escalate,
• withdraws requests whose subject is gone,
• opens a decision record for any in-flight request that is missing one.

It keeps running when workflows are paused. It is not the workflow worker, and it has no setting to tune.

Operations card

The Approvals card on the Operations page shows:

• open requests per kind: “N workflow”, “N group join”, “N vault checkout”,
• a Completion failed count that links to that tab, red when above zero,
• “N vault policies with no reachable approver.”

The Workflows card still shows “N awaiting approval” for runs parked on an Approval step.

Permissions

No new permission was added. Every decision, override, withdrawal and retry is recorded in the administrator audit trail with who, whether as approver or as operator, and the reason. The group and vault hash-chained audit trails keep their own rows (Requested, Approved, Denied, Cancelled, Expired, and so on) exactly as before.

API

The /api/approvals routes need the Enterprise tier. Below it every route is refused with “Enterprise tier required”.

Each list row carries the id, kind, stage, title, subject, requester, justification, when it opened, the escalation and timeout times, the decisions so far and the number needed, the status, who decided and as what (Approver or Operator), the completion status, the requested duration in minutes for a vault row, and whether the caller can decide it.

GET /api/workflows/status and the operations posture carry pendingApprovals { workflow, groupJoin, vaultCheckout }, completionFailedApprovals and policiesWithoutReachableApprover.

Deprecated routes

These routes are kept for one release as wrappers over the new ones. Move integrations to /api/approvals.

• POST /api/group-requests/{id}/approve, /deny and /cancel
• GET /api/groups/requests/pending
• GET /api/groups/requests/pending-admin
• POST /api/vault/checkouts/{id}/decide and /cancel
• GET /api/vault/checkouts/pending. Its list is empty for a vault.admin holder outside the approver role.
• GET /api/workflows/approvals and /api/workflows/approvals/{id}, with /approve and /reject

Retention and erasure

Workflow requests still age out with their runs, under run-history retention. See Retention. Group join and vault request records are removed when their request rows are purged, never on their own.

Erasing a person under DSAR and right to erasure blanks the title, subject name, message, justification and requester name on every request about them or raised by them, of every kind. Who decided, and how, stays on the record.

Upgrading

• Run the database step first. The installer’s database step adds what approvals need. A database updated outside the installer needs the database step run before the Admin API starts. Otherwise the Approvals page, group join requests and vault check-outs fail with an invalid column name.
• Read the reconciler’s lines. On its first start, the Admin API gives every in-flight group join request and every pending vault request its decision record, without sending the notices again. It logs the counts per kind, and each vault policy’s reachable approvers, to the IdentityMesh event log. Until it has run, the old routes answer 409 for an in-flight request.
• Check each vault policy’s approver role. Holders of vault.approve outside a policy’s approver role can no longer approve its requests. A policy with a blank approver role keeps the old behaviour, where any vault.approve holder may decide. Set each policy’s approver role to a role people actually hold, under Settings → User Role Assignments.
• Set the navigation theme again. One sidebar entry, Approvals, replaces the three old entries. An Appearance theme that renamed or hid one of the old entries loses that override; set it again on Approvals. See Appearance.
• Update notification filters. The notification kinds are now ApprovalRequested, ApprovalEscalated, ApprovalDecided, ApprovalTimedOut, ApprovalWithdrawn and ApprovalExpired. Old inbox rows keep working and their links redirect. A SIEM rule or report that filters on the old kind names needs updating.

See Upgrades for the release’s full list.

Troubleshooting