Access Request

Last modified 13 Mar 2024 13:32 +01:00
Table of Contents

Description

The example represents a use-case, where an authorized user requests for membership to a specific role from the role catalogue. The user is limited with a set of authorization permitting the access request and listing of only specific roles.

Such request is then asynchronously processed in an approval workflow. The workflow is based on the default "approval" mechanism of midPoint where a specific user is assigned with the 'approver' relation to a role which assignment should be approved by him.

Authentication methods used to work with the REST api

Authentication methods

Example

In this example we are using the user Jack and authenticating with the password y0uR_P455woR*d on a midPoint instance running on localhost:8080. This is due to the character of the example.

For some help regarding the REST examples please see this link:

How to use MidPoint REST examples

  1. You set the role which we would like to be requestable as "requestable=true" (in our case "96262f4f-053a-4b0b-8901-b3ec01e3509c").

  2. You assign the role as a member of our organizational unit which represents a role catalog (in our case "7878cf5d-9de2-486c-aeb7-41b438200a57").

  3. For a simple approval workflow, we can assign an approver to the role.

  4. The user which is going to request the role, in our case 'Jack', has to have an authorization assigned to him to do this.

  5. In this use case the authorization is "Rest Self Request" present in the example. It is simplified and configured for this specific example.

  6. The user is now capable of requesting the role through the REST api.

  7. The request will create an approval workflow case for the roles approvers.

  8. If you want information regarding the users case, you will have to query the open cases. A REST location header or redirect is currently missing, please see MID-9493.

Show example authorization for "Entitlement self request" | GitHub 
<role xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
        xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
        xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3"
        xmlns:org="http://midpoint.evolveum.com/xml/ns/public/common/org-3"
        xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
        xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
        xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        oid="c19f0234-fbd0-4b69-9ef4-7847a4ff39e2"
        version="1">

    <name>Rest Self Request</name>
    <description></description>
    <activation/>
    <authorization>
        <name>rest</name>
        <description></description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#all</action>
    </authorization>

    <authorization>
        <name>read-requestable-roles</name>
        <description>Allow to read requestable roles. This allows to search for requestable roles in user interface.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read</action>
        <object>
            <type>RoleType</type>
            <filter>
                <q:text>requestable = true AND parentOrgRef/@/name = "Role Catalog"</q:text>
            </filter>
        </object>
    </authorization>

    <authorization>
        <name>assign-requestable-roles</name>
        <description>Allow to assign requestable roles. This allows to request roles in a request-and-approve process.
            The requestable roles will be displayed in the role request dialog by default.
            Please note that the roles also need an approval definition to go through the approval process.
            Otherwise, they will be assigned automatically without any approval.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#assign</action>
        <phase>request</phase>
        <object>
            <special>self</special>
        </object>
        <target>
            <type>RoleType</type>
            <filter>
                <q:text>requestable = true AND parentOrgRef/@/name = "Role Catalog"</q:text>
            </filter>
        </target>
        <relation>org:default</relation>
    </authorization>
    <authorization>
        <name>self-execution-modify</name>
        <description>Authorization that allows to self-modification of some properties, but only in execution phase.
            The real limitation of these operations is done in the request phase.
            E.g. the modification of assignments is controlled in the request phase by using the #assign
            authorization.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#modify</action>
        <phase>execution</phase>
        <object>
            <special>self</special>
        </object>
        <item>assignment</item>
    </authorization>

    <authorization>
        <name>assignment-target-get</name>
        <description>Authorization that allows to read all the object that are possible assignment targets.
            Note that this authorization may be too broad for production use. Normally it should be limited to just
            selected properties such as name and description.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#get</action>
        <object>
            <type>OrgType</type>
        </object>
        <object>
            <type>RoleType</type>
        </object>
        <object>
            <type>ArchetypeType</type>
        </object>
        <object>
            <type>UserType</type>
        </object>
    </authorization>
    <authorization>
        <name>assignment-target-read-case</name>
        <description>Authorization that allows to read approval status of cases. This is used to display requests
            to the end users, especially in the "My Requests" box in user dashboard.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read</action>
        <object>
            <type>CaseType</type>
            <requester>
                <special>self</special>
            </requester>
        </object>
    </authorization>
    <authorization>
        <name>self-owned-task-read</name>
        <description>Authorization that allows to see all tasks owned by a currently logged-in user.</description>
        <action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read</action>
        <object>
            <type>TaskType</type>
            <owner>
                <special>self</special>
            </owner>
        </object>
    </authorization>
</role>
Search for All Requestable Objects which are a Part of the Role Catalog'
curl --user Jack:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/roles/search \
-v \
--data-binary @./samples/rest/query-all-request-targets.json
Show data source example for "Search for All Requestable Objects which are a Part of the Role Catalog" | GitHub 
{
  "query": {
    "filter": {
      "text": "requestable = true AND parentOrgRef/@/name = \"Role Catalog\""
    }
  }
}

The response is an HTTP 200 code in case of success with a response body containing the queried items.

Example Output is a list of objects. 
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
    "object" : [ {
      "@type" : "c:RoleType",
      "oid" : "96262f4f-053a-4b0b-8901-b3ec01e3509c",
      "version" : "5",
      "name" : "employee",
      "parentOrgRef" : {
        "oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
        "relation" : "org:default",
        "type" : "c:OrgType",
        "targetName" : "Role Catalog"
      },
      "metadata" : {},
      "operationExecution" : [],
      "assignment" : {
        "@id" : 3,
        "metadata" : {},
        "targetRef" : {
          "oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
          "relation" : "org:default",
          "type" : "c:OrgType",
          "targetName" : "Role Catalog"
        },
        "activation" : {
          "effectiveStatus" : "enabled"
        }
      },
      "iteration" : 0,
      "iterationToken" : "",
      "roleMembershipRef" : {
        "@metadata" : {},
        "oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
        "relation" : "org:default",
        "type" : "c:OrgType",
        "targetName" : "Role Catalog"
      },
      "activation" : {},
      "displayName" : "Basic Employee",
      "requestable" : true
    } ]
  }
}
Entitlement Self Request
curl --user Jack:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X PATCH http://localhost:8080/midpoint/ws/rest/users/a9885c61-c442-42d8-af34-8182a8653e3c \
-v \
--data-binary @./samples/rest/modify-attribute-assign-entitlement.json
Show data source example for "Entitlement Self Request" | GitHub 
{
  "objectModification": {
    "itemDelta": {
      "modificationType": "add",
      "path": "assignment",
      "value": {
      "targetRef": {
        "oid": "96262f4f-053a-4b0b-8901-b3ec01e3509c",
        "type": "RoleType"
      }
      }
      }
    }
  }

The response is an HTTP 204 code in case of success without a response body.

Search For Open Cases Regarding Specific User
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/cases/search?options=resolveNames \
-v \
--data-binary @./samples/rest/query-approval-for-user.json
Show data source example for "Search For Open Cases Regarding Specific User" | GitHub 
{
  "query": {
    "filter": {
      "text": "state = \"open\" AND objectRef/@/name =\"Jack\""
    }
  }
}

The response is an HTTP 200 code in case of success with a response body containing the queried items.

Example Output is a list of objects. In this example you see both the parent case and also a child case with a work item.

From this information you can deduce what is the state of the case and who is the approver.

Details 
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
    "object" : [ {
      "@type" : "c:CaseType",
      "oid" : "e2f64612-c616-4e08-bace-e9308232553f",
      "version" : "0",
      "name" : {
        "orig" : "Approving and executing change of user \"Jack\" (started Mar 7, 2024, 10:10:59 AM)",
        "norm" : "approving and executing change of user jack started mar 7 2024 101059 am",
        "translation" : {
          "key" : "ApprovingAndExecuting.ChangeOf",
          "argument" : [ {
            "translation" : {
              "key" : "ObjectSpecification",
              "argument" : [ {
                "translation" : {
                  "key" : "ObjectTypeLowercase.UserType",
                  "fallback" : "UserType"
                }
              }, {
                "value" : "Jack"
              } ]
            }
          }, {
            "value" : "Mar 7, 2024, 10:10:59 AM"
          } ]
        }
      },
      "metadata" : {},
      "assignment" : {},
      "archetypeRef" : {},
      "objectRef" : {
        "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
        "relation" : "org:default",
        "type" : "c:UserType",
        "targetName" : "Jack"
      },
      "requestorRef" : {
        "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
        "relation" : "org:default",
        "type" : "c:UserType",
        "targetName" : "Jack"
      },
      "state" : "open",
      "modelContext" : {
        "state" : "primary",
        "channel" : "http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest",
        "focusContext" : {
          "objectOldRef" : {
            "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
            "relation" : "org:default",
            "type" : "c:UserType",
            "targetName" : "Jack"
          },
          "objectNewRef" : {
            "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
            "relation" : "org:default",
            "type" : "c:UserType",
            "targetName" : "Jack"
          },
          "objectTypeClass" : "com.evolveum.midpoint.xml.ns._public.common.common_3.UserType",
          "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
          "iteration" : 0,
          "iterationToken" : "",
          "fresh" : true,
          "secondaryDeltas" : { }
        },
        "focusClass" : "com.evolveum.midpoint.xml.ns._public.common.common_3.UserType",
        "doReconciliationForAllProjections" : false,
        "executionPhaseOnly" : false,
        "projectionWave" : 1,
        "executionWave" : 0,
        "lazyAuditRequest" : false,
        "requestAudited" : false,
        "executionAudited" : false,
        "requestAuthorized" : true,
        "stats" : { },
        "requestMetadata" : {}
      }
    }, {
      "@type" : "c:CaseType",
      "oid" : "b0de0420-7848-4981-88f8-c21b415fcabb",
      "version" : "1",
      "name" : {
        "orig" : "Assigning role \"Basic Employee\" to user \"Jack\"",
        "norm" : "assigning role basic employee to user jack",
        "translation" : {
          "key" : "DefaultPolicyConstraint.Short.assignmentModification.toBeAdded",
          "argument" : [ {
            "translation" : {
              "key" : "ObjectSpecification",
              "argument" : [ {
                "translation" : {
                  "key" : "ObjectTypeLowercase.RoleType",
                  "fallback" : "RoleType"
                }
              }, {
                "value" : "Basic Employee"
              } ]
            }
          }, {
            "translation" : {
              "key" : "ObjectSpecification",
              "argument" : [ {
                "translation" : {
                  "key" : "ObjectTypeLowercase.UserType",
                  "fallback" : "UserType"
                }
              }, {
                "value" : "Jack"
              } ]
            }
          } ]
        }
      },
      "metadata" : {},
      "assignment" : {},
      "archetypeRef" : {},
      "parentRef" : {
        "oid" : "e2f64612-c616-4e08-bace-e9308232553f",
        "relation" : "org:default",
        "type" : "c:CaseType",
        "targetName" : "Approving and executing change of user \"Jack\" (started Mar 7, 2024, 10:10:59 AM)"
      },
      "objectRef" : {
        "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
        "relation" : "org:default",
        "type" : "c:UserType",
        "targetName" : "Jack"
      },
      "targetRef" : {
        "oid" : "96262f4f-053a-4b0b-8901-b3ec01e3509c",
        "relation" : "org:default",
        "type" : "c:RoleType",
        "targetName" : "employee"
      },
      "requestorRef" : {
        "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
        "relation" : "org:default",
        "type" : "c:UserType",
        "targetName" : "Jack"
      },
      "state" : "open",
      "event" : {
        "@type" : "c:CaseCreationEventType",
        "@id" : 3,
        "timestamp" : "2024-03-07T10:10:59.720+01:00",
        "initiatorRef" : {
          "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
          "relation" : "org:default",
          "type" : "c:UserType",
          "targetName" : "Jack"
        }
      },
      "workItem" : {
        "@id" : 4,
        "name" : {
          "orig" : "Assigning role \"Basic Employee\" to user \"Jack\"",
          "norm" : "assigning role basic employee to user jack",
          "translation" : {
            "key" : "DefaultPolicyConstraint.Short.assignmentModification.toBeAdded",
            "argument" : [ {
              "translation" : {
                "key" : "ObjectSpecification",
                "argument" : [ {
                  "translation" : {
                    "key" : "ObjectTypeLowercase.RoleType",
                    "fallback" : "RoleType"
                  }
                }, {
                  "value" : "Basic Employee"
                } ]
              }
            }, {
              "translation" : {
                "key" : "ObjectSpecification",
                "argument" : [ {
                  "translation" : {
                    "key" : "ObjectTypeLowercase.UserType",
                    "fallback" : "UserType"
                  }
                }, {
                  "value" : "Jack"
                } ]
              }
            } ]
          }
        },
        "stageNumber" : 1,
        "createTimestamp" : "2024-03-07T10:10:59.847+01:00",
        "originalAssigneeRef" : {
          "oid" : "472001d8-839f-4a28-acdf-d8d1c81583b0",
          "relation" : "org:default",
          "type" : "c:UserType",
          "targetName" : "JohnM"
        },
        "assigneeRef" : {
          "oid" : "472001d8-839f-4a28-acdf-d8d1c81583b0",
          "relation" : "org:default",
          "type" : "c:UserType",
          "targetName" : "JohnM"
        }
      },
      "approvalContext" : {
        "changeAspect" : "com.evolveum.midpoint.wf.impl.processors.primary.policy.PolicyRuleBasedAspect",
        "deltasToApprove" : {
          "focusPrimaryDelta" : {
            "changeType" : "modify",
            "objectType" : "c:UserType",
            "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
            "itemDelta" : [ {
              "modificationType" : "add",
              "path" : "c:assignment",
              "value" : [ {
                "@type" : "c:AssignmentType",
                "targetRef" : {
                  "oid" : "96262f4f-053a-4b0b-8901-b3ec01e3509c",
                  "type" : "c:RoleType"
                }
              } ]
            } ]
          }
        },
        "immediateExecution" : false,
        "approvalSchema" : {
          "stage" : {
            "@id" : 2,
            "number" : 1,
            "approverRef" : {
              "oid" : "472001d8-839f-4a28-acdf-d8d1c81583b0",
              "relation" : "org:default",
              "type" : "c:UserType",
              "targetName" : "JohnM"
            },
            "outcomeIfNoApprovers" : "reject",
            "groupExpansion" : "byClaimingWorkItem"
          }
        },
        "policyRules" : { }
      },
      "stageNumber" : 1
    } ]
  }
}

See Also

Was this page helpful?
YES NO
Thanks for your feedback