User Stories - Approvals
Last modified 17 Oct 2023 09:54 +02:00
Table of Contents

This document contains user stories for upgrade of design of approvals. It is prepared for planning of development of midPoint version 4.9. Some user stories described here may be already implemented.

This document will be tuned during summer 2023.

1. User Experience

1.1. Improving User Understanding of Approvals

Currently, our approval process includes too much midpoint-specific terminology, such as "delta," which may not be familiar or intuitive to our business users. To enhance the user experience, we should make the approvals more user-friendly and align them with concepts that business users are already familiar with, namely "requests" and "approvals."

In the context of midpoint, we can adopt the following naming convention:

  • Request: This will replace the "Top level case" to represent the initial user request for approval.

  • Case: This term will continue to be used in midpoint, representing the approval process for each request.

  • Workitem: represents the individual tasks or items requiring approval within a case.

Furthermore, we should ensure that all user-facing pages hide the midpoint-specific terminology, presenting a more intuitive interface for business users. The goal is to provide approvers with a clear and straightforward view of the requests they are handling, enabling better communication and collaboration among all parties involved in the approval process.

User Story

AS a business manager who does not know midpoint terminology but needs to approve,
I WANT TO have clear intuitive understanding what is request, case and who has to approve it and when,
SO THAT I won’t get lost in GUI without learning midpoint terminology. I want just to see and understand things I need to approve and use approvals to approve or reject the requests.

Acceptance Criteria

  1. Objects related to the approval should be clearly identified and distinguishable - request/case/workitem.

  2. Approver should have better overview of what is he approving. The user interface for approver should be redesigned.

  3. The approval request/case should contain some high level description of the operation, something like midPoint is already providing in audits, even closer to business terminology.

The attachment may be assigned by requestor or even by approver.

User Story

AS a User requesting access
I WANT TO be able to attach attachment to the request (e.g. email from some manager), or add a link to some other system (website)
SO THAT I can prove reason of my request.

User Story

AS an approver approving request
I WANT TO be able to attach attachment to the request, or add a URL link
SO THAT I can explain better my decision, or
THAT I can provide to requestor or to next approvers some additional information.

1.3. Send Back to Requestor

User Story

AS an Approver
I WANT the ability to send a request back to requestor for additional information
SO THAT I can obtain the necessary details or clarifications required for a complete and accurate evaluation of the request.

Acceptance Criteria

  • When the request is sent back, the requestor should be notified.

  • The status of the request should be appropriately updated to reflect the "information requested" state.

  • Midpoint should allow the requestor to update and resubmit the request after providing the requested information or modify it.

1.4. Better overview of actual request

The request/case should provide overview of the approval status with list of all steps and Approval notes should be visible in a form of discussion chain (chat) - that each approver will be able to read and understand what is happening without unnecessary opening request/case details in all workitems.

User Story

AS a Requestor, Approver who should approve the case, or any authorized user,
I WANT TO see an overview of approval case in one page together with approval notes for each workitem,
SO THAT I don’t need to open each approval step to see the history.

User Story

AS a Requestor
I WANT TO know how long a specific person has had my request (whether they received it yesterday or if it’s been a week)
SO THAT I can be aware of the approval timeline and follow up if necessary.

Acceptance Criteria

  1. when approver opens the approval request/case, he should be able to see the overview of the approval case in one page

    • TODO update our <existing panel> is too sparse and does not provide enough information.

  2. midPoint should provide in the overview:

    • overall status of the approval (e.g.: In progress / Approved / Rejected / Failed(?))

    • all approval steps

    • which step is active and since what time, who should approve now

    • for finished steps: who did what, when, with approval note (short part of it)

      • if approval note is long, then just some part of it with identification (…​) that there is more

  3. the approval overview should be searchable

  4. if provisioning of the approved role requires manual cases, then these workitems should be included also in the overview (see: Include manual tasks in the request workflow).

1.5. Better overview of all my requests in GUI

User Story

AS a User
I WANT TO see all my open requests and their status,
SO THAT I can see easily the requests already done and accesses I can use and
THAT I can identify requests that are not yet approved and contact approver to move it forward if necessary.

User Story

As a User
I WANT TO see all my requests that I have created together with their status
SO THAT I can see what requests I raised in specific situation (e.g. for a project start).

Acceptance criteria

  1. midPoint can provide searchable view where user can see all his requests with their status.

    • The view should provide information of what was requested and some details to the request.

  2. by clicking on each request the user can go to the details.

  3. midPoint offers IAM administrator the ability to define length of these historical requests to be stored. Typically a year or 2.

1.6. Automatic Approval if Requestor = Approver

AS an engineer configuring approvals,
I WANT TO configure approval step to be approved automatically when requestor is the same as approver,
SO THAT users don’t experience unnecessary approvals.

Acceptance Criteria

  • The IAM engineer configuring approvals should have an option to enable such automatic approval.

  • The automatic approval should be applied in any step of the approval.

  • When the automatic approval feature is enabled, midPoint should check if the requestor is the same as the approver at any stage of the approval process.

  • If the requestor is the same as the approver, the request should be automatically approved without any additional steps.

  • The IAM engineer configuring approvals should be able to disable the automatic approval feature for specific types of requests or stages, providing flexibility in the approval setup.

  • The automatic approval should be logged in the history of approvals with identification of automatic approval.

1.7. Automatic approval if approver was in the approval already

AS and IAM engineer configuring approvals,
I WANT TO configure approval step to be approved automatically, if the approver was already in the approval and approved the request,
SO THAT approval process won’t be waiting for duplicate approval by the same person.

Example

This can happen, if request should be approved by user’s manager and system owner and the manager is also the system owner.

Acceptance criteria

  • midpoint should provide engineer an option to configure approval policy that it will be approved automatically if the approval was already approved

1.8. New manager - access to historical data

User Story

AS a IAM administrator or engineer,
I WANT TO ensure that when a manager is replaced, the new manager can access the historical data of requests, cases and workitems associated with the previous manager,
SO THAT changes of managers will not break approval processes and new manager can continue in the work of the previous one.

Acceptance Criteria

  1. When a new manager takes over, he/she should have the necessary permissions in midPoint to access historical records of their predecessor’s activities and decisions.

  2. The access to the historical data should be controlled by complex computation of authorization (more resource intensive) or by administrative procedure (requires additional automated or manual operation).

  3. midPoint should provide option to keep or remove access to historical data by old manager.

  4. The configuration of the definition should be well documented with examples provided.

  5. The solution in midPoint should be scalable and efficient, allowing for smooth access to historical data even in cases of frequent manager changes.

1.9. Approve on behalf of

The concept of "attorney" does not align well with business context in many organizations. Commonly used terms are "deputy" and "on behalf of." The term "attorney" is not a widely recognized business term and should be replaced.

User Story

AS a deputy of an Approver
I WANT TO be able to perform approvals on his/her behalf,
SO THAT requests will not be delayed if the approver is unavailable.

Acceptance Criteria

  1. I should have the authorization to act as a deputy approver for the specific approver.

  2. When the authorized approver is not available, I can perform approvals on their behalf.

  3. End user should see that the approval was performed by me as the deputy approver (on behalf of).

  4. Requests should continue to be processed and not wait for the approver’s presence, ensuring timely approvals even in their absence.

  5. midPoint should display information that the request was approved by <my name> on behalf of <the original approver>.

  6. Term "attorney" should not be used in GUI.

1.10. Include manual tasks in the request workflow

If the role being assigned is provisioned via manual connector, or the provisioning takes significant time (e.g. an hour for full reconciliation of the account in cloud), then finish of an approval is not the end and user don’t have the access when the approval is done.

When the access is approved, it is not ready in such case. User would obtain incorrect information.

User Story

AS a User requesting an assignment of a role,
I WANT TO be informed not only when the request is fully approved, but also when the final provisioning is done,
SO THAT I know that I can test the access and don’t need to wait for anything else.

Acceptance Criteria

If there are manual cases required in provisioning of the assignment, then midpoint should provide following information:

  1. Final approval notification should state information that there are additional manual operations

  2. The request should be enhanced by these manual cases, so the user can see that manual operation is under progress and by which team(s)

  3. User can see the related manual cases in the request and can monitor their status in the GUI - the same way as approval workitem

  4. User obtains final notification when all manual cases are closed

Next user story describes the same situation from different point of view.

User Story

AS a Role Manager / IAM Operations Manager / Security Officer
I WANT TO monitor not only approval phase but also provisioning as well
SO THAT I can verify that request are fully fulfilled, and they did not fail during provisioning.

1.11. Assignment parameter specification - creation of access request

To avoid role explosion, an option to define assignment parameters should be implemented in midPoint. Having such assignment parameters, users will need some options how to handle them. See also: Parametric roles / assignment parameters.

User Story

AS a User or User Manager,
I WANT TO request specific access and define additional parameter better specifying such access (role assignment),
SO THAT I can request my access more naturally and don’t need to search over many similar roles (avoid role explosion).

Examples

  • User requests mailbox and defines parameter for the mailbox size during request.

Notes

  • probably GUI updates will be necessary, but we could handle this very similar to time constraints

    • or we can add additional step to request access wizard to add parameters to such parametric roles

  • how to handle parametric roles included in business roles ?

  • if a role has parameters, probably it could be selected from predefined values. This should be able to be read in UI. User should select from predefined parameters.

1.12. Assignment parameter specification - approval of access request

User Story

AS a User or User Manager,
I WANT that if there is specific technical information necessary during access configuration, then this information is added to the request (assignment) by responsible technician during the approval or realisation,
SO THAT I don’t need to ask for technical information I don’t understand and don’t need for my business work.

Examples

  • User requests a mailbox role, but the email system administrator defines size of the mailbox during the approval.

  • User requests role, but application owner limits assignment validity for the next 3 months.

1.13. Assignment validity modification - approval of access request

User Story

AS an application owner approving access request,
I WANT TO limit assignment validity for the next 3 months only,
SO THAT I don’t need to certify or request

Note: This User story may be handled similarly as previous one. Ot the use case may be handled by sending the request back to the requestor with requesting modification of validity.

1.14. Access modification request

User Story

AS a User or Business Manager,
I WANT TO request modification of a parameter of specific access for myself or subordinates,
SO THAT I can align the access to my business needs or compliance requirements.

Examples

  • User wants to extend assignment of a role by a month

  • User has a "mailbox" role with parameter size=1GB, but he wants to increase the size to 10 GB.

Acceptance Criteria

  1. midPoint should provide a user-friendly interface for modification of assignments parameters.

  2. the request for removal may go through approval workflow too. It should be different workflow.

  3. project manager may request removal of the accesses for members of his project team

  4. access removal request should be clearly identified in the requests

Do we want to modify parameters also of inducements or just for assignments ?

1.15. Specific approval workflow for different parameter value

User Story

AS an IAM engineer,
I WANT TO add specific approval step for an access when this access is assigned with specific parameter,
SO THAT I can increase control over assignment of specific access level without unnecessarily increasing number of approvals.

Examples

  • Assigning access with level "reader" to a GIT repository is approved jut by user’s manager, but assigning the same role with "developer" has to be approved by the repository owner.

Acceptance Criteria

  1. midPoint should allow specification of different approval workflows for specific parameter values.

  2. The values should be set while requesting the access

1.16. Notification instead of approval

User Story

AS an IGA Manager, IAM engineer.
I WANT TO replace specific approval step in specific approval workflow (role or person) just by notification to the approver,
SO THAT I can optimize provisioning performance for specific roles or specific team.

Examples

  • A manager in some org. unit doesn’t need to approve any request of his subordinates of risk level up to 2 (see Risk based approach for approval). He just wants to be informed.

Acceptance Criteria

  1. IAM engineer can configure replacement of specific approval step by notification for approval of assignment of specific role

  2. IAM engineer can configure replacement of specific approval step by notification for approval of assignment requested by specific person or team

  3. Approver who was skipped will obtain notification for each request.

  4. Midpoint provides the approver interface for listing all requests that he was just notified (for specified period of time)

    • IAM engineer can define limit how to get back to history - maybe a year max

1.17. Access removal

Midpoint should provide interface for removing of access from other users. Business managers can ask for removal of accesses of their subordinates, a privileged user (e.g. security officer) can remove accessed of users based on specific business request (e.g. user is fired instantly).

See Access removal vs certification triggered by business user in Approvals Design Notes for difference when direct access removal and certification is to be used.

User Story

AS a User or Business Manager,
I WANT TO remove specific accesses for myself or my subordinates,
SO THAT I can avoid paying license fees for accesses that are not utilized by me or my team, thereby optimizing costs.

Acceptance Criteria

  1. midPoint should provide a user-friendly interface for removing user access directly by user himself or by other user with priviledges,

  2. the request for removal may go through approval workflow too. It should be different workflow.

  3. project manager may request removal of the accesses for members of his project team

  4. access removal request should be clearly identified in the requests

1.18. Approval of access removal

In some cases it is useful that access removal will be approved. But not all of them.
See Certification triggered by business user in User Stories - Certifications for more details about how to handle such certifications.

User Story

AS a IAM engineer
I WANT TO configure policy that specific access removals will be approved by specific users SO THAT these users can minimize operational issues caused by such removal.

Acceptance Criteria

2. Big picture / reporting over requests and approvals

2.1. Request analysis

User Story

AS a Role Manager, IAM Operations Manager, or Security Officer
I WANT TO obtain big picture information about requests and their approvals
SO THAT I can effectively manage IAM operations and also processes related to it.

Particularly I WANT TO

  • know how many requests of what type were created in specific period, SO THAT I have basic information of number of manual work necessary.

  • know which roles are most frequently requested for a given period, SO THAT I can optimize rule configurations and automate assignments.

  • identify requests that required most approvers, SO THAT I can address any inefficiencies or bottlenecks.

  • identify requests with the longest approval times, SO THAT I can investigate and address any delays in the approval process within the organization.

  • track the total number of requests created and the average approval time for each request, including the time necessary for 90% or 95% of the requests to be approved/rejected SO THAT I can set and manage user’s expectation of request fulfillment speed.

Monitoring average approval time is not enough. Managing and communicating 90% or 95% level is much better for setting the user expectations and managing the perceived speed of the process.
Acceptance Criteria

  1. midPoint should provide searchable view for authorized personnel that will provide information requested above

  2. midPoint should provide the statistics separately for different types of requests, without mixing them together

  3. If provisioning of the assigned roles requires manual tasks, then this time should be included in the fulfillment time (see: Include manual tasks in the request workflow).

User Story

AS a Role Manager / IAM Operations Manager
I WANT TO see statistics from specific request analysis for time periods
SO THAT I can identify trends and manage processes.

2.3. Better view of open requests in user (object)

User Story

AS business user
I WANT TO see easier that user (myself) or other object has open requests/cases when I open the object
SO THAT I won’t miss that user (or myself) has something "in progress" and therefore may not be applied in his access yet.

The notification is already visible over the cases, but business user can miss it quite often. Something better visible, but not very aggressive - not necessary to click on it.

3. REST interface

3.1. Approval via REST

Midpoint must have options to approve/reject requests via REST.

User Story

AS an IT manager+ I WANT TO all requests were approved in our internal tool
SO THAT people (managers) can perform their basic daily approval tasks from one place - the same environment and see what they approved and when.

Acceptance Criteria

GIVEN company has its own application that is used for performing approve/reject operations. This application can connect to midpoint via REST.
WHEN an approver has to approve request
THEN the application is able to show request with basic information (what was requested, when, who, approval notes). User is able to approve, reject the request (together with writing the note).
If the user needs more details, he is able to get directly to midpoint via link.

We need to resolve issue listed already in Approvals via REST howto

See also: MID-6067

The application may not necessarily mimic all the details provided in midpoint. If user needs more info, the link should be available to get to approval case in midpoint.

4. IAM Engineer experience

The updates in 4.9 should provide better interface to engineer. It should provide easier configuration and better overview of what is already configured in the system. So the engineer is more efficient and inexperienced engineers can get into midPoint faster.

4.1. Default configuration of notifications

User Story

AS an engineer configuring approvals and it’s notifications,
I WANT TO have default or initial configurations available that I can use as a starting point for my own configurations,
SO THAT I can expedite the process of setting up approvals and notifications and deliver my results faster.

Acceptance Criteria

Default configuration of notifications should provide following notifications:

  1. Notifications to requestor:

    • When the request is created: "Your request of assigning role XYZ was created."

    • optionally, if requestee is not the same as requestor: "Request of assigning role XYZ to you was created by <requestors name>."

    • At the end of the approval, when all approvals are done and the request is approved: "You request of assigning role XYZ was approved", or "Your request was rejected"

    • if there are manual operations, the final approval notification should state information that there are additional manual operations

  2. Notifications to approver:

    • Notifications to approver: "Your approval is required for …​"

  3. Optional notification to requestor:

    • When the request is sent back to requestor, then the requestor should obtain notification: "Your request was returned to you by <name>"

4.2. Approving specific changes of specific users (VIP users).

How to handle situation when I want to approve modification of specific attributes for specific people. Typically such people is top management of the organization.

User Story

AS an IAM Administrator,
I WANT the ability to approve modifications of specific attributes or assignments for certain individuals coming from authoritative sources,
SO THAT I can control and validate changes made to critical data for the designated users.

Example

  • The email attribute comes from source system to midPoint. I want to approve modification of email attribute for top management. To be sure that top management won’t get email change.

Acceptance Criteria

  1. midPoint should allow to specify rules (policy rules, "mapping policy rules" ?) for approving modification of specific attributes or assignments of specific users.
    This is already possible, just configuration si very complex and resource intensive. See below.

  2. IAM administrator should easily identify such attributes and approval rules

  3. When IAM administrator decides to reject the modification, the subsequent reconciliations should not trigger additional approval requests until the source attribute is changed again

    • maybe we can use shadow marks for this

  4. The approval should be auditable

  5. IAM administrator should be notified about the requested approval

  6. When the modification is rejected, the "rule of not using authoritative value" should be created.

  7. IAM administrator can easily list, identify and manage such rules

  8. When situation changes, IAM administrator can delete the "rule of not using authoritative value" and modification can be applied to the user. Or approval is raised again and IAM administrator can approve it.

  9. The configuration should be well documented prepared with examples for engineers.

In the version 4.7, the policy probably rules allows such configuration using extension attribute to be filled from inbound source and mapping defined in object template. Just the solution requires additional extension attribute, increasing performance requirements (new global policy rule) and not providing all features defined in acceptance criteria above.

4.3. Parametric roles / assignment parameters

User Story

AS a IAM Engineer,
I WANT TO define parameters for a role,
SO THAT I can avoid role explosion.

Examples

  • Role "mailbox" with parameter "size". Value is enumerated from: "1GB", "5GB", "10GB", "unlimited".

  • IAM is controlling access to GIT. Each repository as individually. Concept is defined that users can access repository as Owner/Reader/Contributor/Maintainer. When new private repository is created, it is loaded as service into midPoint and users can request access.

  • User can create spaces in confluence via midPoint. Space has 2 parameters: name of the space (free text), and access level - enumerated values. User requests the

Acceptance Criteria

  1. midPoint should provide option for definition of roles or other objects (services) with parameters. There may be more than one parameter.

  2. parameters should be defined as enumerated or free text

  3. the assignment parameter must be visible in GUI and all reports as it is necessary attribute specifying access

  4. while requesting the access user should be able to select parameter value from predefined values or specify its value

  5. the role configuration should allow filling out the parameter in specific step of approval workflow

  6. midPoint should provide options for management of access parameters also via REST interface.

Was this page helpful?
YES NO
Thanks for your feedback