Table of Contents

Changing user permissions

A direct change of permission, i.e. adding/editing/removing a link between an identity and a role directly (via REST api) is not possible. All permission changes can be made via the role request agenda (RoleRequest).

Role request agenda

This agenda contains all requests (wishes) for requested changes of authorized identities. The main idea is that all changes in identities' permission must go through this agenda. Therefore, it is not intended only for end users' requests but for automatic operations (synchronization, automatic roles, etc.) as well.

The standard scenario of a permission change is as follows:

If the user creates a new request but does not submit it, it will be displayed as "Concept" in the table "Unfinished requests for permission change" in the assigned roles tab. Thus they can return to an unfinished concept.

Concept table

The goal is to provide the user with a comfortable way of creating the requested permission changes (they can see all the change in one location, projected into their currently assigned roles).

The request can be submitted only when the request is in the "CONCEPT", "DUPLICATED" or "EXCEPTION" states

Changing permission without approval

There are two ways of how to make a change in permission without approval.

Disabling the approval processor

As mentioned above, after submitting a request, an event is called out which is captured by processor "role-request-approval-processor". If we disable this processor, all submitted requests will be realized immediately without any approval.

By disabling the approval processor, all submitted requests will be realized immediately for all users in the system regardless of their permissions.

Request attribute "Execute immediately"

A request for permission change contains attribute "executeImmediately". If this attribute is set to "true", the request will be executed immediately after submitting it. A submission without approval can be executed only by users having permission "ROLEREQUEST_EXECUTEIMMEDIATELY". If an event marked in this way is executed by a user without this permission, an exception will be called out.

Systematically, it is possible to execute a submission of an event without approval even without having the required permission. Method "IdmRoleRequestService.startRequestInternal" serves this purpose. This method is not available through the REST interface.

Duplicate request

During the process of submitting a request, it is verified if there is another duplicate request of the new request (in state "IN_PROGRESS", "APPROVED"). If a duplicate request is found, the executed request is labelled as duplicated (state "DUPLICATED") and its attribute "duplicatedToRequest" is filled with the identifier of the duplicate request (a record is made in the request log). The submission (execution) of the request is thus suspended.

A duplicate request is such a request with equivalent:

A duplicate request can be submitted (executed) repeatedly. Due to this, duplicate requests are found again.

Request removal

A request can be removed completely only in "CONCEPT" state. If it is in "EXECUTED" state, every attempt to remove it ends in exception "ROLEREQUESTEXECUTEDCANNOTDELETE". If it is in "APPROVED, IN_PROGRESS, EXCEPTION, DUPLICATED" states, the request is set to "CANCELED" state. If a process is tied to the request, the process is terminated (subsequently a record about this is made in the request log).

Request agenda for administrators

A situation when the end user creates a request for permission change from their profile has been described above. For administrators, it is convenient to use the "Role requests" agenda, which provides an overview of all requests in the system. All requests in all states are displayed in this agenda (including those already executed).

The agenda allows a direct request submission from a list of requests. The agenda also allows creating a new request, where the administrator must first choose the user who the request is being created for.

In addition, the request detail in this agenda contains (compared to the end user request detail) a possibility of ticking that the request is not to be approved. The request detail also contains a log. This log contains all crucial information which occur during the life cycle of the request (errors, duplicates, request cancellation due to integrity, executed operations, etc.).

REST interface

The creation of a request via a REST interface has the following steps:

  1. Creation of the request
  2. Creation of the role concepts (requested permission changes)
  3. Execution of the request (submitting the request)

Creation of the request

A request can be created via method POST on endpoint "/api/v1/role-requests/".

Example of a request:

{
  "applicant" : "846164b4-8272-46a7-ba69-0bfdad652aff",
  "requestedByType" : "MANUALLY",
  "conceptRoles" : [],
  "executeImmediately" : false,
  "description" : "Please check and approve the permission change"
}

Creation of the role concepts

A role concept can be created via method POST on endpoint "/api/v1/concept-role-requests/".

Example of a request (creation of a concept for assigning a new role):

{
 "roleRequest":"740d7dc3-d90b-40cd-80f9-80cf36180c80",
 "identityContract":"7fdf1128-ce2d-4d34-ba99-821a544ad753",
 "role":"6ac36596-4f68-4282-88de-685e654199d6",
 "identityRole":null,
 "roleTreeNode":null,
 "validFrom":null,
 "validTill":"2017-07-31",
 "operation":"ADD"
}

Execution of the request

Execution of the request can be done via method PUT on endpoint "/api/v1/role-requests/{requestId}/start", where requestId is the UUID of the created request.

During the approval process, the requested changes can be changed (e.g. the manager disagrees with assigning of the role and removes it from the request). For easy backtracking of how the original request looked like, it is converted to JSON format at its start and saved to the request (attribute originalRequest. For the sake of a clearer arrangement, this attribute is not stated in the example below.

Example of a response (request in IN-PROGRESS state):

{
   "id": "740d7dc3-d90b-40cd-80f9-80cf36180c80",
   "created": "2017-03-22T08:57:03.385Z",
   "modified": "2017-03-22T09:12:45.617Z",
   "creator": "admin",
   "creatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
   "modifier": "admin",
   "modifierId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
   "originalCreator": "admin",
   "originalCreatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
   "originalModifier": "admin",
   "originalModifierId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
   "trimmed": false,
   "applicant": "846164b4-8272-46a7-ba69-0bfdad652aff",
   "state": "IN_PROGRESS",
   "requestedByType": "MANUALLY",
   "wfProcessId": "2621",
   "conceptRoles": [   {
      "id": "974f0941-20e8-44ff-b387-425460ee2546",
      "created": "2017-03-22T09:07:37.189Z",
      "modified": null,
      "creator": "admin",
      "creatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
      "modifier": null,
      "modifierId": null,
      "originalCreator": "admin",
      "originalCreatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
      "originalModifier": null,
      "originalModifierId": null,
      "trimmed": true,
      "roleRequest": "740d7dc3-d90b-40cd-80f9-80cf36180c80",
      "identityContract": "7fdf1128-ce2d-4d34-ba99-821a544ad753",
      "role": "6ac36596-4f68-4282-88de-685e654199d6",
      "identityRole": null,
      "roleTreeNode": null,
      "validFrom": null,
      "validTill": "2017-07-31",
      "operation": "ADD",
      "state": "CONCEPT",
      "wfProcessId": null,
      "log": null,
      "_embedded":       {
         "identityContract":          {
            "id": "7fdf1128-ce2d-4d34-ba99-821a544ad753",
            "created": "2017-03-21T14:10:59.496Z",
            "modified": null,
            "creator": "[SYSTEM]",
            "creatorId": null,
            "modifier": null,
            "modifierId": null,
            "originalCreator": "[SYSTEM]",
            "originalCreatorId": null,
            "originalModifier": null,
            "originalModifierId": null,
            "trimmed": true,
            "identity": "846164b4-8272-46a7-ba69-0bfdad652aff",
            "validFrom": null,
            "validTill": null,
            "guarantee": null,
            "position": "Default",
            "externe": false,
            "disabled": false,
            "_embedded": {"identity":             {
               "id": "846164b4-8272-46a7-ba69-0bfdad652aff",
               "created": "2017-03-21T14:10:59.071Z",
               "modified": null,
               "creator": "[SYSTEM]",
               "creatorId": null,
               "modifier": null,
               "modifierId": null,
               "originalCreator": "[SYSTEM]",
               "originalCreatorId": null,
               "originalModifier": null,
               "originalModifierId": null,
               "trimmed": true,
               "username": "kopr",
               "_embedded": {}
            }}
         },
         "role":          {
            "id": "6ac36596-4f68-4282-88de-685e654199d6",
            "created": "2017-03-21T14:10:54.859Z",
            "modified": null,
            "creator": "[SYSTEM]",
            "creatorId": null,
            "modifier": null,
            "modifierId": null,
            "originalCreator": "[SYSTEM]",
            "originalCreatorId": null,
            "originalModifier": null,
            "originalModifierId": null,
            "trimmed": true,
            "name": "superAdminRole",
            "disabled": false,
            "version": null,
            "roleType": "SYSTEM",
            "priority": 0,
            "approveAddWorkflow": "approveRoleBySuperAdminRole",
            "approveRemoveWorkflow": "approveRemoveRoleBySuperAdminRole",
            "description": null,
            "subRoles": null,
            "superiorRoles": null,
            "authorities": null,
            "_embedded": {}
         },
         "roleRequest":          {
            "id": "740d7dc3-d90b-40cd-80f9-80cf36180c80",
            "created": "2017-03-22T08:57:03.385Z",
            "modified": "2017-03-22T09:12:45.617Z",
            "creator": "admin",
            "creatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
            "modifier": "admin",
            "modifierId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
            "originalCreator": "admin",
            "originalCreatorId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
            "originalModifier": "admin",
            "originalModifierId": "0e49f109-cdc0-495f-b69a-2456fd2ced54",
            "trimmed": true,
            "applicant": "846164b4-8272-46a7-ba69-0bfdad652aff",
            "state": "IN_PROGRESS",
            "requestedByType": "MANUALLY",
            "wfProcessId": "2621",
            "conceptRoles": [],
            "executeImmediately": false,
            "duplicatedToRequest": null,
            "log": null,
            "description": "Please check and approve the permission change",
            "_embedded": {"applicant":             {
               "id": "846164b4-8272-46a7-ba69-0bfdad652aff",
               "created": "2017-03-21T14:10:59.071Z",
               "modified": null,
               "creator": "[SYSTEM]",
               "creatorId": null,
               "modifier": null,
               "modifierId": null,
               "originalCreator": "[SYSTEM]",
               "originalCreatorId": null,
               "originalModifier": null,
               "originalModifierId": null,
               "trimmed": true,
               "username": "dill",
               "_embedded": {}
            }}
         }
      }
   }],
   "executeImmediately": false,
   "duplicatedToRequest": null,
   "log": null,
   "description": "Please check and approve the permission change",
   "_embedded":    {
      "wfProcessId":       {
         "processDefinitionId": "approve-identity-change-permissions:1:36",
         "id": "2642",
         "name": "Approve by manager",
         "startTime": "2017-03-22T09:12:45.569+0000",
         "endTime": null,
         "durationInMillis": null,
         "startUserId": null,
         "deleteReason": null,
         "priority": 50,
         "assignee": null,
         "createTime": "2017-03-22T09:12:45.569+0000",
         "dueDate": null,
         "completeTaskDecision": null,
         "taskVariables": {},
         "candicateUsers":          [
            "admin",
            "svanda",
            "kopr"
         ]
      },
      "applicant":       {
         "id": "846164b4-8272-46a7-ba69-0bfdad652aff",
         "created": "2017-03-21T14:10:59.071Z",
         "modified": null,
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": null,
         "modifierId": null,
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": null,
         "originalModifierId": null,
         "trimmed": true,
         "username": "dill",
         "_embedded": {}
      }
   },
   "_links": {"self": {"href": "http://localhost:8080/idm-backend/api/v1/role-requests/740d7dc3-d90b-40cd-80f9-80cf36180c80"}}
}

The approval process

If the request-permission-change-without-approval mode is not used, process "approve-identity-change-permissions" will be started. This process ensures the approval of the request as a whole and its base implementation is composed of these parts:

The input of the proces is the event which started the approval process. This event contains the request itself (IdmRoleRequestDto). At the end of the process the event is called out again (performs the realization).

Approval by the helpdesk department

Approval by the manager

Approval by the manager is disabled by default

.

Approval by the user administration department

Approval by the user administration department is disabled by default.

.

Execution of approving subprocesses

Every constituent role being requested (change or assignment) can be approved separately. Due to that, a separate subprocess is always run for every role.

If the role is evaluated as not requiring approval, default process "change-role-without-approve" is run. This process only generates the name (it is saved in the history of workflow processes) and changes the state of the role concept to "APPROVED".

Setting of the approval process to a role

The approval process (for assigning or changing an ssigned role) is set to the role by setting the relevant priority. The role's priority can have values (0,1,2,3,4), where every priority can be assigned a different approval process.

The specific priority assignment and the type of approval process is defined in the application configuration:

idm.sec.core.wf.role.approval.{priority}={wf}

,where {priority} is the priority number and {wf} is the key of the process workflow.

There is only one process approving removal of assigned roles for the whole application (all priorities). Again, it can be defined in the application configuration under key "idm.sec.core.wf.role.approval.remove". The default process is "approve-remove-role-by-manager"
To make removing of a role approved, it is necessary that the role item "Approve role removal" is ticked.

The default setting of priorities and approval processes is as follows:

Approval by the security department

Approval by the security department is disabled by default

.

Automatic skipping of approval processes

Automatic skipping of approval processes is performed if the request realizator (the one who really submitted it) is the same user as the currently logged-in user and, at the same time, is among the candidates who can approve this task. In that case, the task is skipped with the same result as if it was approved manually.

Approve, disprove task by task detail

To task detail is possible to get from url in notification (email and etd.), after click to url in notofication you will be redirected to task detail. After aprove, disaprove or go back you will be redirected to all your tasks. When is reopend already denied or approved task, user recive information about nonexisting or solved task.

Beware if url with task is copy by ctrl+c and paste directly to web browesr by ctrl+v, user will be redirected to the page on which he was (for example google.com, blank page, etc.)

Security

Authorization policies are implemented fo role requests agenda. Concept role requests are secured by assigned role request internally. Only identity with authority ROLEREQUEST_ADMIN can read all concepts without filter by role request through the IdmConceptRoleRequestController.